Example

Query two operations sites

One bounded feature query, shown server-first and then through equivalent JavaScript, Python, and .NET calls against the same FeatureServer fixture.

Server contract first

Bounded feature query

supported

Fixture endpoint: http://127.0.0.1:8080/rest/services/admin_sample/FeatureServer/3000/query
Service manifest key: server-fixture:tests/seed/admin-sample-feature-server.yaml#admin_sample/3000
Evidence: pinned-fixture at honua-server:trunk
Server version: current trunk fixture contract
Owner: honua-server data plane
Support: Community

Authentication

Anonymous for the seeded local fixture; deployments may require X-API-Key or Authorization and must not embed credentials in the page.

Cancellation

Abort the HTTP request. No server job is created by this bounded query.

Errors

HTTP problem/GeoServices error envelopes are surfaced by each SDK's typed transport error; unsupported semantic compilation must fail closed.

Server capability IDs

FeatureServer Query (serve.geoservices-featureserver)OGC API Features (serve.ogc-api-features)OData v4 (serve.odata)

available

geoservices-featureserver

GET or POST /rest/services/{serviceId}/FeatureServer/{layerId}/query

This is the admitted cross-language route and fixture receipt.

Open GET endpoint ↗

{
  "method": "GET or POST",
  "endpoint": "http://127.0.0.1:8080/rest/services/admin_sample/FeatureServer/3000/query",
  "payload": {
    "f": "json",
    "where": "status = 'online'",
    "outFields": "objectid,name,status,priority",
    "geometry": "-157.95,21.28,-157.70,21.41",
    "geometryType": "esriGeometryEnvelope",
    "spatialRel": "esriSpatialRelIntersects",
    "inSR": 4326,
    "outSR": 4326,
    "orderByFields": "objectid ASC",
    "resultRecordCount": 2,
    "returnGeometry": true
  }
}

{
  "objectIds": [
    300001,
    300003
  ],
  "featureCount": 2
}

partial

ogc-api-features

GET /ogc/features/collections/{collectionId}/items

The server route and parameters are real. The admin_sample collection identifier is not pinned by the FeatureServer seed contract, so this variant is not labeled equivalent until an OGC fixture receipt binds it.

{
  "method": "GET",
  "endpoint": "/ogc/features/collections/{collectionId}/items",
  "payload": {
    "filter": "status = 'online'",
    "bbox": [
      -157.95,
      21.28,
      -157.7,
      21.41
    ],
    "properties": [
      "objectid",
      "name",
      "status",
      "priority"
    ],
    "sortby": "+objectid",
    "limit": 2
  }
}

{
  "requiredSemanticIds": [
    300001,
    300003
  ]
}

partial

odata-v4

GET /odata/Features

The OData read/query route is real, but this request intentionally lacks a claimed equivalent spatial predicate and fixture binding; those are explicit admission gaps.

{
  "method": "GET",
  "endpoint": "/odata/Features",
  "payload": {
    "$filter": "LayerId eq 3000 and status eq 'online'",
    "$select": "objectid,name,status,priority,Geometry",
    "$orderby": "objectid asc",
    "$top": 2
  }
}

{
  "requiredSemanticIds": [
    300001,
    300003
  ]
}

Normalized semantics

{
  "filter": {
    "field": "status",
    "operator": "eq",
    "value": "online"
  },
  "fields": [
    "objectid",
    "name",
    "status",
    "priority"
  ],
  "limit": 2,
  "spatial": {
    "relation": "intersects",
    "bbox": [
      -157.95,
      21.28,
      -157.7,
      21.41
    ],
    "crs": "EPSG:4326"
  },
  "returnGeometry": true
}

{
  "featureCount": 2,
  "objectIds": [
    300001,
    300003
  ],
  "allStatuses": "online"
}

Semantic assertionSort returned objectid values numerically and require exactly [300001, 300003], two features, status=online on every feature, and non-null point geometry.

Evidence

honua-server/tests/seed/admin-sample-feature-server.yaml
serve.geoservices-featureserver: 49/49 operations implemented
serve.ogc-api-features: 21/21 operations implemented
serve.odata: 30/30 operations implemented

Limits and blockers

The pinned semantic receipt is FeatureServer-first; OGC and OData variants require their own route receipts before the gallery labels them equivalent.
Python OData support is read/query only, not write parity.

Server references

Unpinned upstream reference withheld
Unpinned upstream reference withheld

Equivalent client surfaces

Choose a language without changing the job.

Source<T>.query(Query<T>)Exact API reference &nearr;

import { HonuaClient, createDataset, envelope, queryFilter } from '@honua/sdk-js';

const controller = new AbortController();
const client = new HonuaClient({ baseUrl: 'http://127.0.0.1:8080' });
const source = createDataset({
  id: 'operations', client, capabilityPolicy: 'strict',
  sources: [{ id: 'operations-sites', protocol: 'geoservices-feature-service', locator: { serviceId: 'admin_sample', layerId: 3000 }, capabilities: ['query'] }]
}).source('operations-sites');
const result = await source.query({
  filter: queryFilter.eq('status', 'online'),
  spatialFilter: envelope(-157.95, 21.28, -157.70, 21.41, { wkid: 4326 }),
  outFields: ['objectid', 'name', 'status', 'priority'],
  pagination: { limit: 2 }, returnGeometry: true, signal: controller.signal
});

honua_sdk.source.Source.queryExact API reference &nearr;

from honua_sdk import HonuaClient, SourceDescriptor, SourceLocator

with HonuaClient('http://127.0.0.1:8080', timeout=10.0) as client:
    source = client.source(SourceDescriptor(id='operations-sites', protocol='geoservices-feature-service', locator=SourceLocator(service_id='admin_sample', layer_id=3000)))
    result = source.query(where="status = 'online'", out_fields=['objectid', 'name', 'status', 'priority'], bbox=(-157.95, 21.28, -157.70, 21.41), limit=2, return_geometry=True)

IHonuaFeatureServerClient.QueryAsync(string, int, FeatureServerQueryParams, CancellationToken)Exact API reference &nearr;

using Honua.Sdk.GeoServices.FeatureServer.Models;

var page = await features.QueryAsync(
    "admin_sample", 3000,
    new FeatureServerQueryParams { Where = "status = 'online'", OutFields = "objectid,name,status,priority", ResultRecordCount = 2, ReturnGeometry = true, SpatialFilter = new FeatureServerSpatialFilter { Geometry = "{\"xmin\":-157.95,\"ymin\":21.28,\"xmax\":-157.70,\"ymax\":21.41,\"spatialReference\":{\"wkid\":4326}}", GeometryType = "esriGeometryEnvelope", SpatialRel = "esriSpatialRelIntersects" } },
    cancellationToken);

Exact reference matrix

Raw contract and public symbols

Surface	Operation or symbol	Package and version	Ownership and behavior
Raw HTTPavailable	`GET\|POST /rest/services/{serviceId}/FeatureServer/{layerId}/query` Unpinned upstream link withheld	Honua Server min current trunk fixture contract - Community	honua-server data plane Auth: Anonymous fixture; API key or bearer token where configured. Cancel: Client disconnect/request abort. Errors: GeoServices JSON error envelope plus HTTP status.
CLIgap	Gap: The current Python honua CLI exposes services, layers, style apply, and doctor; it has no query subcommand or --help reference.	Not applicable min n/a - Unavailable	SDK/CLI Auth: Not applicable. Cancel: Not applicable. Errors: Not applicable.
JavaScriptavailable	`Source<T>.query(Query<T>)`	@honua/sdk-js min 0.1.4-beta.0 - Stable root contract	honua-sdk-js Auth: HonuaClient apiKey/auth and request interceptors. Cancel: Query.signal: AbortSignal. Errors: HonuaCapabilityNotSupportedError and typed transport errors.
Pythonavailable	`honua_sdk.source.Source.query`	honua-sdk min 0.1.10 - Alpha	honua-sdk-python Auth: HonuaClient api_key, bearer_token, or auth_provider. Cancel: Sync calls use timeout; AsyncSource.query participates in asyncio task cancellation. Errors: HonuaHttpError subclasses, HonuaAuthenticationError, HonuaTransportError, and HonuaTimeoutError.
.NETavailable	`IHonuaFeatureServerClient.QueryAsync(string, int, FeatureServerQueryParams, CancellationToken)`	Honua.Sdk.GeoServices min 1.2.1 - Supported	honua-sdk-dotnet Auth: HonuaGeoServicesClientOptions bearer/API-key provider and HttpClient handler pipeline. Cancel: CancellationToken on QueryAsync. Errors: Honua GeoServices typed exception plus HttpClient transport exceptions.

Console configuration

Planned UI, raw contract only

Route: Not implemented
Required role: Not defined
Visual receipt: Not captured

{
  "copyable": "The complete raw HTTP query is the primary configuration."
}

No screenshot published.

null This remains not-applicable until a real route and golden receipt exist.

Optional AI context - experimental

@honua/sdk-js/nl-map-control createNlMapControl().propose()/execute()

Allowed drafting tasks

discover capabilities
explain the schema
draft a bounded normalized query plan

Context inputs

capability manifest
source descriptor
schema
service metadata
bounded tool schemas

Provider and data boundary

Bring-your-own LLM callback; the SDK sends bounded tool schemas and semantic map context, depends on no provider SDK, and persists no prompt/model output.

Injection and privacy boundary

Treat service metadata as untrusted context, reject credential/cursor/endpoint-bearing plans, bound retries and effects, and never place secrets in prompts or approval envelopes.

Deterministic validation

propose() must render the normalized NlMapPlan, query-plan IR, limits, fields, spatial envelope, and fingerprint before execute(); fixture replay verifies deterministic plan and receipt digests.

Approval boundary

Planning never executes. Read-only auto-execution is policy-controlled; MCP protected-source reads and all effectful plans require a signed, single-use approval.

Prohibited autonomous actions

execute without required human approval
silently widen a filter
invent a source capability
send credentials to a model

Fallback and provenance

Use the raw request inspector or one of the three explicit SDK tabs without AI.

Show provider/model digests, plan fingerprint, approval digest when used, result digest, and signed execution receipt; omit raw prompts and result payloads from audit events.