Skip to main content

Query Data

The query_data tool queries a feature layer or table for records or aggregations. It must always be called after Describe Layer, which provides the field metadata required to construct a valid query.

Tool name

query_data

Tool alias

Query Data

Objective

Query a feature layer or table inside a feature service or map service for records or aggregations using SQL WHERE clauses, spatial filters, pagination, sorting, and statistical aggregations.

Usage guidance

query_data provides an interface for querying a feature layer or table for records or aggregations, after the layer's metadata has been retrieved by using describe_layer.

Important:

Call describe_layer first

query_data must only be used after describe_layer has been invoked on the target layer. The layer reference may come from a content search, a direct URL, or other context. Calling query_data before describe_layer is considered a failed run. Use the metadata returned by describe_layer to build a valid SQL-92 WHERE clause and to identify legal field names—otherwise hallucinated field names will cause empty or failed queries.

Default behavior

  • The default response returns all attributes but not the geometry for matching records, capped at the top 100 matching records. This default keeps responses small and avoids overwhelming clients.

  • Both the page size and the geometry behavior can be overridden through the inputs below—for example, when paginating, or when the client explicitly asks for geometries. Pagination is available only when the layer's supportsPagination property is true.

  • When no aggregations are provided, the tool performs an additional total-count query so it can tell the client whether more records are available beyond the first page.

Caution:

While clients can be instructed to retrieve full result sets through pagination, you should do so cautiously: large result sets can be slow to process, and a geoprocessing tool may be a better fit for very large queries.

Inputs

The tool exposes 14 input parameters. Required parameters are marked; everything else is optional.

  1. layerOrTableUrl (required)—The URL of the layer or table to query.

  2. where—A SQL WHERE clause to filter results by attribute. Use only the field names returned by describe_layer to avoid hallucinated columns.

  3. geometry—A JSON-formatted Esri geometry string used to filter results spatially. Pass it as a JSON string representing a valid Esri JSON geometry object. Keep the geometry as simple as possible and derive it directly from a tool call or other conversational context. The geometry's spatial reference must be included in the JSON string. If the spatial reference is missing, the geometry is interpreted in the layer's spatial reference. When the coordinates use a different spatial reference, such as longitude and latitude against a layer in Web Mercator, the query may return incorrect results or fail. Example formats by geometry type:

    • Point (esriGeometryPoint): {"x":1.0,"y":2.0,"spatialReference":{"wkid":4326}}

    • Multipoint (esriGeometryMultipoint): {"points":[[1.0,2.0],[3.0,4.0]],"spatialReference":{"wkid":4326}}

    • Polyline (esriGeometryPolyline): {"paths":[[[0,0],[1,1],[2,2]]],"spatialReference":{"wkid":4326}}

    • Polygon (esriGeometryPolygon): {"rings":[[[0,0],[1,0],[1,1],[0,1],[0,0]]],"spatialReference":{"wkid":4326}}

    • Envelope (esriGeometryEnvelope): {"xmin":0,"ymin":0,"xmax":1,"ymax":1,"spatialReference":{"wkid":4326}}

  4. geometryType—Required whenever geometry is set. Valid values: esriGeometryPoint, esriGeometryMultipoint, esriGeometryPolyline, esriGeometryPolygon, esriGeometryEnvelope.

  5. spatialRelationship—The spatial relationship to apply between the input geometry and the layer features. Defaults to esriSpatialRelIntersects. Valid values:

    • esriSpatialRelIntersects—The default; features sharing any part of their geometry with the input geometry. Use for intersects or distance-from queries.

    • esriSpatialRelContains—Features fully contained within the input geometry.

    • esriSpatialRelWithin—Features that fully contain the input geometry.

    • esriSpatialRelCrosses—Features that cross the input geometry.

    • esriSpatialRelOverlaps—Features that overlap the input geometry.

    • esriSpatialRelTouches—Features that touch the boundary of the input geometry.

    • esriSpatialRelEnvelopeIntersects—Features whose envelope intersects the input envelope. Cheaper than a full intersects.

    • esriSpatialRelIndexIntersects—Features whose envelope intersects the input geometry's index entry. Cheaper still and approximate.

  6. bufferDistance—A distance to buffer the supplied geometry by, before applying the spatial filter. The distance is applied in the output spatial reference (outSR) if one is provided; otherwise, it is applied in the spatial reference of the input geometry, or in the layer's spatial reference.

  7. bufferUnits—Required when a buffer distance is specified. Valid values: esriSRUnit_Foot, esriSRUnit_Meter, esriSRUnit_Kilometer, esriSRUnit_StatuteMile, esriSRUnit_NauticalMile, esriSRUnit_USNauticalMile.

  8. outSR—An optional spatial reference WKID (well-known ID) for returned geometries, for example 4326 or 3857.

  9. statistics—A list of aggregations for advanced analysis of the layer's data. Provide them only when explicitly requested, or when the layer's describe_layer output makes it obvious the client is asking for statistics (such as counts, minimums, or maximums). Each statistic specifies:

    • A statistic type (statisticType)—One of count, min, max, avg, sum, stddev, var.

    • A field to compute on (onField)—must be a field returned by describe_layer.

    The output attribute name for each statistic is auto-generated as {statistic_type}_{statistic_field} (for example, avg_pop for the average of pop). Use this naming convention when reading the statistics array of the response and when referencing a statistic from orderByFields.

  10. groupByField—A field used to group statistical results. Do not use it unless statistics are requested. Must be a field returned by describe_layer.

  11. orderByFields—A list of fields to sort by. Each entry specifies a sort order plus either a field name (from describe_layer) or a statistic name in the {statistic_type}_{statistic_field} form, such as sum_population or avg_income (most useful when a group-by is specified).

  12. pageSize—Pagination size for non-aggregation queries. Defaults to 100, maximum 1000. Be cautious about increasing this—larger pages can cause client-side errors due to very large tool responses. The service's maxRecordCount setting can also limit the number of records returned per page, even when pageSize is higher.

  13. resultOffset—Pagination offset for non-aggregation queries, used together with pageSize to retrieve later pages. Defaults to 0. Works only when the layer's supportsPagination property is true.

  14. returnGeometry—Whether to include geometries on matching features. Defaults to false to keep responses lightweight.

When to use

  • The client wants to query a specific layer or table within a feature service or map service, and the agent has already called describe_layer on it.

  • The client only needs the first page of results (100 by default, up to 1,000, subject to the service's maxRecordCount setting), or is asking exploratory questions that involve filtering.

When not to use

  • The request requires complex geoprocessing beyond what a simple feature-layer query can provide. Use a geoprocessing tool instead.

  • The agent has not yet called Describe Layer on the target layer. Always call describe_layer first.

Sample prompts to test the tool

Send any of the prompts below to your MCP-compatible AI client to verify that query_data is working correctly. Each prompt targets a different combination of the tool's inputs—attribute filters, sorting, pagination, statistics, group-by, geometry filters, buffer distances, and spatial-relationship modes.

Note:

These prompts are for illustration only. Before you use them, modify them to match the data published in your ArcGIS Enterprise environment.

Important:

Several prompts specify coordinates as longitude and latitude. Verify that the agent includes the matching spatial reference (WKID 4326) in the geometry it passes to query_data. If the spatial reference is missing and the layer uses a different one, the query may return incorrect results or fail.

Basic attribute filter with sorting and pagination

  • Show me the first 10 counties in California with a population greater than 500,000, sorted by population in descending order. Then show me the next page of results.

Statistics with group-by and ordered results

  • For each road classification type in the San Francisco Streets layer, what is the average travel speed, minimum speed, maximum speed, and total count of street segments? Sort by average speed descending.

Spatial filter using a polygon geometry

  • Find all hospitals and fire stations in San Francisco that fall within the bounding box of downtown SF (roughly between -122.42, 37.77 and -122.39, 37.80). Return their geometries too.

Point geometry with buffer distance

  • Which parks in San Francisco are within 1 kilometer of coordinates longitude -122.4194, latitude 37.7749 (City Hall)? Return their names and geometries.

Global statistics without group-by

  • Across all US cities in the USA map service with a population over 100,000, what is the total population sum, average population, and the standard deviation of population values?

Spatial relationship—within with geometry plus attribute filter

  • Which California cities are completely within the bounding box of Southern California (longitude -118.9 to -116.9, latitude 32.5 to 34.5) and have a population over 50,000? Sort them by name alphabetically.

Statistics + group-by + where + buffer (full coverage)

  • Within 5 miles of San Francisco City Hall (longitude -122.4194, latitude 37.7749), group the street segments by road classification and give me the count, average speed, and max speed for each group—only include segments with a travel speed greater than 0. Order by count descending.