Query languages and interfaces

ShrikeDB exposes several query surfaces over one database because graph patterns, RDF queries, nearest-neighbor retrieval, key-value access, analytics, and operational automation have different natural interfaces. This chapter explains where each surface fits and how they compose.

Interface map

Surface Best fit Result shape Primary entry point

Cypher

Property-graph matching, paths, aggregation, graph algorithms, and graph/vector/KV composition

Rows of named bindings

ExecuteCypher

SPARQL

RDF graph patterns, named graphs, ontology vocabulary, aggregates, and constructed result graphs

Bindings or an RDF result graph

ExecuteSPARQL; standalone default-graph INSERT DATA and DELETE DATA through ExecuteSPARQLUpdate

Vector RPCs

Direct nearest-neighbor retrieval and batch search

Entity IDs and scores

VectorSearch, packed variants

Graph/KV RPCs

Loaders and low-level application access

Typed protobuf messages

Graph, KV, bulk, and transaction methods

SpaceKey

Bounded geographic and spatiotemporal observation search

Observation rows and work counters

Cypher procedure, SPARQL service, or HTTP

Semantic MCP

Profile-guided natural-language analysis and agent tooling

Typed plan, result data, and evidence

MCP tools

Lakehouse query fabric

Reviewed views over registered Parquet sources

Rows with source and mapping evidence

Semantic or query-planner route

Cypher

Use Cypher for node and relationship patterns. ShrikeDB supports read pipelines built from MATCH, OPTIONAL MATCH, WHERE, WITH, UNWIND, RETURN, ordering, pagination, aggregation, collection operations, unions, bounded subqueries, and finite path forms covered by the compatibility reference.

MATCH (customer:Customer)-[:PLACED]->(order:Order)-[:CONTAINS]->(item:Item)
WHERE order.created_at >= $start
WITH customer, sum(item.price) AS total
WHERE total >= $minimum
RETURN customer.id AS customer_id, total
ORDER BY total DESC
LIMIT 50

Cypher also hosts procedures for vector KNN, key-value hydration, graph analytics, weighted paths, and SpaceKey. Catalog and data mutations use explicit server gates described in Cypher Writes And Schema.

Read Cypher for usage and Cypher And openCypher Compatibility for clause-by-clause semantics.

SPARQL

Use SPARQL for triples, RDF terms, optional graph patterns, property paths, named graphs, and ontology-oriented data. SELECT returns bindings; ASK returns a boolean; supported CONSTRUCT forms return a derived result graph.

PREFIX ex: <https://example.com/schema/>
PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>

SELECT ?supplier (COUNT(?shipment) AS ?shipments)
WHERE {
  ?shipment a ex:Shipment ;
            ex:supplier ?supplier ;
            ex:departureTime ?time .
  FILTER (?time >= "2026-09-01T00:00:00Z"^^xsd:dateTime)
}
GROUP BY ?supplier
ORDER BY DESC(?shipments)

ShrikeDB local SERVICE extensions expose weighted paths and SpaceKey without sending the query to a remote SPARQL endpoint. Remote services are rejected by policy. ExecuteSPARQL serves reads; a separately gated ExecuteSPARQLUpdate method applies ordered default-graph INSERT DATA and DELETE DATA operations on a standalone server. See SPARQL for the request and operating limits.

Read SPARQL for graph, aggregate, path, and service examples.

Direct vector, graph, and KV APIs

Direct gRPC methods are appropriate when an application already knows the primitive operation. They avoid parsing a query language and provide typed batch and streaming messages.

Use:

  • vector search RPCs for one or many nearest-neighbor requests;

  • graph scan and neighbor RPCs for low-level traversal services;

  • KV methods for exact key access and bulk loading;

  • transaction RPCs when supported writes must commit together;

  • Cypher or SPARQL when the operation requires joins, aggregation, projection, or language semantics.

The generated gRPC API documents message fields and links to public protobuf downloads.

Semantic queries and MCP

Semantic query tools compile a profile-guided question into a typed plan. Profiles define domain concepts, identifiers, mappings, and allowed analyses. The response can include the selected plan, evidence, provenance, and a Cypher-equivalent inspection representation.

Use this surface for governed analytical assistants. Use direct Cypher or SPARQL when the client already owns the exact query text. See Natural-language questions and Connect an MCP agent.

Parameters and result values

Parameterize application values instead of building query text through string concatenation. Parameter support depends on the expression position and selected execution path; individual language chapters call out literal-only positions such as the current vector.knn index name and candidate count.

Cypher returns named bindings from RETURN. SPARQL returns variables from SELECT. Direct RPCs return schema-defined protobuf messages. Preserve integer, floating-point, boolean, byte, string, UID, list, map, node, relationship, and null distinctions in the client.

Explain, profile, and diagnose

Prefix a supported read query with EXPLAIN to inspect planning without executing the child query. PROFILE executes the query and reports plan and runtime evidence:

PROFILE
MATCH (account:Account)-[:TRANSFERRED_TO]->(peer:Account)
WHERE account.region = $region
RETURN peer, count(*) AS transfers
ORDER BY transfers DESC
LIMIT 20

Use Query planning and execution to understand parsing, semantic gates, planning, snapshot pinning, execution, and fallback. Use Results And Inspection for response and trace fields.

Choose a surface

  • Connected entities and path structure: Cypher.

  • RDF vocabulary and constructed triples: SPARQL.

  • One primitive nearest-neighbor or exact-key operation: direct gRPC.

  • Geographic observations bounded by place and time: SpaceKey.

  • A profile-governed natural-language workflow: semantic MCP.

  • External Parquet that remains authoritative: reviewed lakehouse mapping.

The same application can use more than one surface. Keep database, subject, schema, authentication, and snapshot selection consistent as the request moves between them.