Searching & Filtering

Searching for features

The search() function is the starting point for most queries. Pass tag filters as keyword arguments:

// Find restaurants
search(amenity: "restaurant");

// Find supermarkets that sell organic
search(shop: "supermarket", organic: "yes");

Element types

By default, search() returns all element types (nodes, ways, and relations). Pass a type as the first argument to filter:

// Nodes only (points)
search(node, amenity: "cafe");

// Ways only (lines and polygons)
search(way, building: *);

// Relations only
search(relation, type: "route");

// Explicit all (same as default)
search(nwr, amenity: "school");

You can also pass multiple types by listing them: search(node, way, ...) searches both nodes and ways.

Dataset source

Query your own custom datasets using the dataset() source function:

// Query a single dataset by slug
search(dataset("store-locations"));

// Query multiple datasets
search(dataset("stores", "warehouses"));

// Mix custom data with OSM features
search(dataset("stores"), node, amenity: "cafe")
  .within(boundary(name: "Manhattan"));

// All standard methods work on dataset results
search(dataset("office-locations"))
  .around(500, point(40.7484, -73.9856))
  .limit(10);

Dataset slugs are assigned when you create a dataset via the REST API. You can query up to 20 datasets in a single dataset() call. See the Datasets guide for upload and management details.

ID filter

Look up specific elements by OSM ID:

// Single ID
search(node, id: 12345);

// Multiple IDs
search(node, id: [1, 2, 3]);

// Combine with other filters
search(way, id: [100, 200, 300], highway: *);

Tag filters

PlazaQL supports seven tag filter types:

// Exact match
search(amenity: "cafe");

// Not equals
search(amenity: !"fast_food");

// Regex match
search(name: ~"^Star");

// Case-insensitive regex
search(name: ~i"starbucks");

// Negated regex
search(name: !~"McDonald");

// Key exists (any value)
search(amenity: *, wheelchair: *);

// Key does not exist
search(amenity: "cafe", drive_through: !*);

Multiple filters in the same search() are combined with AND — all must match.

Key and value regex

Both the key and value in a tag filter can be regex patterns. This is useful for matching tag families or numeric values across multiple keys:

// All address tags that start with a number
search(node, ~"^addr:": ~"^[0-9]");

// Any name tag (name, name:en, name:de, etc.) with any value
search(node, ~"^name:": *);

// Find elements with any addr: tag
search(~"^addr:": *);

Key regex uses the ~"pattern" syntax on the left side of the colon. Combine it with value patterns (exact, regex, exists) on the right.

Tag filtering with .filter()

The .filter() method applies tag filters after search or set operations. It uses the same syntax as search() tag filters:

// Filter a union — find all food places, keep only wheelchair-accessible
$food = search(amenity: "restaurant") + search(amenity: "cafe");
$food.filter(wheelchair: "yes");

This is especially useful after combining sets, where you want to filter the combined result:

$mc = search(name: "McDonald's");
$sb = search(name: "Starbucks");
$bk = search(name: "Burger King");

($mc + $sb + $bk)
  .within(geometry: $berlin)
  .filter(wheelchair: "yes", diet__vegan: *)
  .limit(count: 50);

Multiple .filter() calls combine with AND:

search(amenity: "restaurant")
  .filter(cuisine: ~"italian")
  .filter(outdoor_seating: "yes");

Expression filters

For filtering based on computed values — tag arithmetic, string operations, or geometry properties — use .filter() with an expression instead of tag syntax:

// Capacity greater than 50
search(amenity: "theatre")
  .within(geometry: $berlin)
  .filter(number(t["capacity"]) > 50);

// Roads longer than 1km
search(way, highway: "primary")
  .within(geometry: $city)
  .filter(length() > 1000);

// Buildings with area over 500 sq meters
search(way, building: *)
  .bbox(40.7, -74.0, 40.8, -73.9)
  .filter(area() > 500);

Expression filters use the full expression language — tag access with t["key"], arithmetic operators, geometry functions, and comparisons. See the Expressions section for the complete reference.