Type System & Advanced

Type system

PlazaQL has a fully inferred type system. You never declare types — the compiler tracks them through your chain and catches errors.

How types flow

search(node, amenity: "cafe")     // → PointSet
  .around(500, point(38.9, -77.0)) // → PointSet (spatial filter preserves type)
  .centroid()                       // → PointSet (centroid of points = points)
  .limit(count: 10);               // → PointSet

search(amenity: "cafe")            // → GeoSet (no type = mixed)
  .within(geometry: $berlin)        // → GeoSet
  .buffer(50)                       // → PolygonSet (buffer always → polygons)
  .simplify(10);                    // → PolygonSet

Chain ordering

Methods are grouped into three ordering categories:

Group	Methods	Rule
Freely orderable	spatial (.within(), .around(), .bbox(), …), .filter(), transforms (.buffer(), .simplify(), .centroid()), joins (.member_of(), .has_member()), computed columns (.elevation(), .distance(), …), output shape (.fields(), .precision(), …)	Can appear in any order relative to each other
Narrowing	.first(), .last(), .index()	Converts GeoSet → GeoElement; must come after spatial/join filters
Ordering	.sort(), .limit(), .offset()	Must come after all freely orderable methods
Output mode	.count(), .ids(), .tags(), .skel(), .geom()	Must be last in chain, max one
Aggregation	.sum(), .avg(), .min(), .max(), .group_by().count()	Terminal — must be last in chain

Spatial filters, tag filters, transforms, computed columns, and output shape methods can be freely mixed and reordered. This means all of these are valid:

// Buffer before spatial filter
search(amenity: "school")
  .buffer(50)
  .within(geometry: $city);

// Filter after transform
search(node, amenity: "cafe")
  .buffer(50)
  .filter(cuisine: "italian");

// Computed column before transform
search(node, amenity: "cafe")
  .within(geometry: $berlin)
  .elevation()
  .buffer(50);

Additional constraints:

• .limit() must come before .offset()

Error messages

PlazaQL gives precise, actionable errors with source locations:

error: .buffer() (transform) cannot follow .limit() (ordering) — ordering methods must come after all other methods
  --> query:3:5
   |
 3 |     .limit(10).buffer(50)
   |               ^^^^^^^^^^^ transform after ordering
   |
   = hint: move .buffer(50) before .limit(10)

error: .count() is terminal — no methods can follow it
  --> query:4:5
   |
 4 |     .count().limit(10)
   |              ^^^^^^^^^ not allowed after terminal
   |
   = hint: remove .limit(10) or move it before .count()

Keyword vs positional arguments

All functions support both styles. You cannot mix them in a single call:

// Keyword (preferred — self-documenting)
.around(distance: 500, geometry: point(lat: 38.9, lng: -77.0))

// Positional (concise)
.around(500, point(38.9, -77.0))

Expressions

PlazaQL has a full expression language for computing values from tags, element properties, and geometry. Expressions are used in .filter(), aggregation functions (.sum(), .avg()), and .group_by().

Tag access — t["key"]

Access any tag value with t["key"]. Tag values are always strings in OSM:

t["name"]           // → "Starbucks"
t["amenity"]        // → "cafe"
t["building:levels"] // → "5"
t["capacity"]       // → "200"

Property accessors

Built-in functions that return element metadata:

Function	Returns	Example
id()	OSM ID (integer)	id() > 1000000
type()	Element type string	type() == "way"
lat()	Latitude (float, nodes only)	lat() > 48.0
lon()	Longitude (float, nodes only)	lon() < 2.5

Geometry functions

Compute geometric properties of each feature:

Function	Returns	Description
length()	meters (float)	Geometric length of a way. Returns 0 for nodes.
area()	square meters (float)	Area of a closed way or relation. Returns 0 for open ways and nodes.
is_closed()	boolean	Whether a way’s first and last nodes are the same.

length() is always geometric length in meters. For string length, use size().

Type coercion — number()

Tag values are strings. Use number() to cast them for arithmetic:

number(t["capacity"])    // "200" → 200
number(t["height"])      // "12.5" → 12.5
number(t["lanes"])       // "3" → 3

number() is required for arithmetic on tag values. Without it, t["capacity"] > 50 compares strings, not numbers.

is_number() tests whether a tag value can be parsed as a number (returns boolean):

// Only include elements where population is a valid number
.filter(is_number(t["population"]))

String functions

Function	Description	Example
starts_with(str, prefix)	True if str starts with prefix	starts_with(t["name"], "St")
ends_with(str, suffix)	True if str ends with suffix	ends_with(t["name"], "Park")
str_contains(str, substr)	True if str contains substr	str_contains(t["cuisine"], "italian")
size(str)	String length (characters)	size(t["name"]) > 3

str_contains() is used instead of contains() to avoid conflict with the spatial .contains() method. size() is used instead of length() to avoid conflict with geometric length().

Operators

Arithmetic (requires number() for tag values):

Operator	Description	Example
+	Addition	number(t["lanes"]) + 1
-	Subtraction	number(t["height"]) - 3
*	Multiplication	number(t["width"]) * number(t["length"])
/	Division	area() / 1000

Comparison:

Operator	Description	Example
>	Greater than	number(t["capacity"]) > 50
<	Less than	length() < 100
>=	Greater or equal	number(t["height"]) >= 10
<=	Less or equal	area() <= 500
==	Equal	type() == "way"
!=	Not equal	t["name"] != "Unknown"

Logical:

Operator	Description	Example
&&	Logical AND	number(t["lanes"]) > 2 && length() > 500
||	Logical OR	t["amenity"] == "cafe" || t["amenity"] == "restaurant"
!	Logical NOT	!is_closed()

Operator precedence (highest to lowest)

1. ! (unary NOT)
2. *, /
3. +, -
4. >, <, >=, <=
5. ==, !=
6. &&
7. ||

Use parentheses to override: (a || b) && c.

Expression examples

// Roads longer than 1km with more than 2 lanes
search(way, highway: *)
  .within(geometry: $city)
  .filter(length() > 1000 && number(t["lanes"]) > 2);

// Large buildings (area over 1000 sq meters)
search(way, building: *)
  .bbox(40.7, -74.0, 40.8, -73.9)
  .filter(area() > 1000);

// Closed ways that aren't tagged as buildings
search(way)
  .within(geometry: $area)
  .filter(is_closed() && t["building"] == !*);

// Restaurants with valid capacity over 100
search(amenity: "restaurant")
  .within(geometry: $city)
  .filter(is_number(t["capacity"]) && number(t["capacity"]) > 100);

// Total lane-kilometers of roads in a city
search(way, highway: *)
  .within(geometry: $city)
  .filter(is_number(t["lanes"]))
  .sum(number(t["lanes"]) * length() / 1000);

Structural joins

Structural joins let you navigate the membership graph — relations contain members (nodes, ways, other relations), and ways contain nodes. Two methods express this relationship from opposite directions.

.member_of() — filter to members of a source

Keep only elements that are members of the given source set. The first argument is a variable reference or an inline search() expression. Use the optional role: keyword argument to filter by membership role.

// Bus stops that belong to route 42
$$ = search(node, highway: "bus_stop")
  .member_of(search(relation, route: "bus", ref: "42"), role: "stop");

.member_of() works with relations (which have typed members) and ways (which contain ordered nodes).

.has_member() — filter to elements containing a source

The reverse of .member_of(). Keep only elements that contain the given source elements as members.

// All subway lines that pass through a specific station
$my_stop = search(node, railway: "station")
  .around(distance: 500, lat: 40.75, lng: -73.99).first();

$$ = search(relation, route: "subway").has_member($my_stop);

Narrowing

Narrowing methods transform a set into a single element (GeoSet → GeoElement). This distinction matters for the type system — see Attribute access below.

.first() — first element

$stop = search(node, highway: "bus_stop")
  .around(distance: 500, lat: 40.75, lng: -73.99).first();

.last() — last element

$end = search(node, highway: "bus_stop")
  .within(geometry: $route).last();

.index(n) — nth element (1-indexed)

$second = search(node, amenity: "cafe")
  .around(distance: 1000, geometry: point(48.85, 2.35)).index(2);

Attribute access

Extract tag values from variables using bracket syntax: $var[attr].

// Get the ref tag from $stop
$stop[ref]

// Use as a filter value
search(node, highway: "bus_stop", ref: $stop[ref]);

The type of the variable determines how the attribute value is used in SQL:

• On a GeoElement (after .first(), .last(), or .index()): produces a scalar — exact match with = in SQL.
• On a GeoSet (no narrowing): produces a value set — multi-value match with ANY(...) in SQL.

Example queries

// Bus stops on route 42
$$ = search(node, highway: "bus_stop")
  .member_of(search(relation, route: "bus", ref: "42"), role: "stop");

// Subway transfer map — all stations on lines through a nearby stop
$my_stop = search(node, railway: "station")
  .around(distance: 500, lat: 40.75, lng: -73.99).first();
$lines = search(relation, route: "subway").has_member($my_stop);
$$ = search(node, railway: "station").member_of($lines);

// Attribute join — all stops sharing the same ref as a nearby stop
$stop = search(node, highway: "bus_stop")
  .around(distance: 500, lat: 40.75, lng: -73.99).first();
$$ = search(node, highway: "bus_stop", ref: $stop[ref])
  .bbox(40.7, -74.0, 40.8, -73.9);

// Cross-source — route ref matched against a custom dataset
$route = search(relation, route: "bus").bbox(40.7, -74.0, 40.8, -73.9).first();
$$ = search(point, dataset: "my_transit", route_ref: $route[ref]);

Resources

• Playground — Try PlazaQL interactively at plaza.fyi/playground
• API Reference — Full endpoint documentation in the API Reference
• GitHub — Language spec, grammars, and examples at github.com/plazafyi/plazaql