Geospatial and spatiotemporal indexing

Use an authenticated connection when required by your deployment. The following shell example assumes Bash and curl. Set the HTTP address first:

The index name ais is created by the first successful append. The example uses event ID 1 and entity 1001; use a new index or unused increasing event IDs if trying it on an existing database. Add x-shrikedb-database to select a non-default database. On a local single-tenant server, omit the Authorization header below; otherwise set SHRIKEDB_ACCESS_TOKEN to your access token.

Append a batch using the existing authentication headers and optional x-shrikedb-database selector:

An HTTP batch contains 1–10,000 observations. The response acknowledges a durable generation and returns normalization receipts, including source CRS and grid resolution. Keep these receipts with source metadata when provenance matters. An identical retry with the same batch token returns the original batch generation, including after later appends or a restart; different normalized contents with the same token are rejected. New event IDs must exceed the published maximum. Entity IDs may repeat, and timestamps may arrive out of order within the configured domain. The index preserves multiple observations at the same place and time. Choose the immutable time domain for the expected workload: a narrower domain produces finer time bins. The default spans 1970–2100; changing the domain requires a new index.

Indexes are isolated by database and authenticated subject. They are explicit event indexes: appending graph properties does not automatically populate them. To join observations to graph nodes, use that node’s UID as entity, or maintain an explicit MMSI-to-node mapping. Using MMSI as an entity ID does not create a corresponding graph node.

HTTP ingestion commits each batch as a database transaction. Applications that need graph, vector, KV, and geospatial writes to become visible together can call BeginTransaction, buffer the writes with the corresponding transaction RPCs including TransactionInsertSpaceKey, and finish with CommitTransaction. A failed or rolled-back transaction does not publish its geospatial batch.

Numeric points and grid references are distinct input forms. GARS and USNG inputs represent cell centers, not exact sensor fixes or cell-overlap predicates. Other datums and ambiguous bare UTM inputs are rejected rather than guessed. Radius predicates use great-circle distance on a sphere of radius 6,371,008.8 meters; they are not ellipsoidal survey distances.

Find observations near a port during a half-open UTC interval:

A box shape uses WGS84 longitude/latitude fields west, south, east, north. Bounds are inclusive; west > east crosses the antimeridian. A radius shape uses longitude, latitude, and meters; radius_crs accepts any supported coordinate input as position. Omit shape for time-only or entity-track lookups.

Add entity:1001 to restrict a vessel, or cycle:{period:'day',start_ms:72000000,end_ms:21600000} to select UTC 20:00–06:00 across dates. Weekly phases start Monday at 00:00 UTC. There is no implicit local-time or daylight-saving conversion.

For a count without materializing events:

count_only returns one row even for zero matches and cannot yield event fields. Ordinary results can be joined and aggregated using existing Cypher operators. Two static time-window scans can be joined by entity and ordered timestamp to test a vessel’s sequence of observed locations. Such joins return observation pairs; deriving distinct port visits or interpolated trajectories remains application logic. Options are literal maps; per-row correlated index arguments are not supported.

Use the proprietary internal SERVICE endpoint with a single request subject:

The JSON uses the same query options as Cypher. Output predicates use the same field names. Two SERVICE blocks sharing ?vessel can join indexed observation windows; ordinary FILTERs can compare their timestamps. This is a ShrikeDB-specific local SERVICE endpoint. Remote endpoints, SERVICE SILENT, correlated inputs, unknown options, and duplicate bindings are rejected.

Use the count example above to compare returned matches with candidates and seeks. Selective position/time windows can avoid examining much of the index; a full-domain search may still scan all observations. Measure end-to-end requests on your own query mix when sizing a deployment.

The default deadline is 10 seconds, candidate budget 20 million, and result budget 100,000 events. Use timeout_ms, max_candidates, and max_results to set explicit limits; hard maxima are 60 seconds, 100 million candidates, and 10 million results. A budget failure returns an error rather than an incomplete answer. max_cells (default 512) and seek_budget (default 64) bound each cover; a full-coverage segment uses a contiguous scan. Limits apply to the whole pinned query, not separately to every segment.

SpaceKey observations, multidimensional index entries, receipts, and manifests are stored as ordered records in ShrikeDB’s ACID key–value engine. Ingestion writes bounded immutable chunks through the database WAL, then publishes the completed run by replacing one checksummed catalog-head record. Readers pin each named index once per execution; a later append does not alter that reader’s generation. For a multimodal transaction, query snapshot capture and commit publication use a shared visibility gate. A Cypher or SPARQL request therefore sees the graph and geospatial state before the commit or after it, without observing the publication interval between them. Historical graph snapshot queries still reject SpaceKey scans because the SpaceKey procedure pins its named-index generation rather than a historical graph version.

HA deployments carry SpaceKey writes in the same transaction prepare/finalize payload as graph, vector, and KV writes. Peer apply is idempotent by operation and batch identity, and an acknowledged commit uses the configured transaction quorum and durable decision-recovery path. Cypher and SPARQL execute against the locally published replica generation.

Each record key includes the owner, database namespace, named index, and format incarnation. Each ingestion request accepts at most 10,000 observations. Named indexes grow through content-addressed directory pages with 256 run descriptors per page and a constant-size publication head. A validation catalog reopened 1,025 full logical runs representing 10.25 million observations and appended generation 1,026. Storage capacity, configured query budgets, and operational retention policy determine the practical size. Catalog-wide time and entity orders allow a time-window or entity lookup to scan one ordered range per cover instead of seeking once per immutable run. Existing inline catalogs are upgraded on their next append; the upgrade backfills these two global orders before publishing the paged head. Database startup recovers the index through the ordinary KV WAL. When opening an older native SpaceKey catalog, ShrikeDB validates and replays its original batches into KV storage, then archives the legacy directory after migration succeeds.

SpaceKey strings use the original 60-bit / 20-level Unicode profile. Their meaning includes the index’s immutable time domain; keys from different domains are not interchangeable.