gRPC API

Use gRPC for database reads, writes, query execution, and identity management. The examples use grpcurl; applications can generate clients from the same API definitions.

Download the API definitions

Download these files from the guide and save both in a local directory such as $HOME/shrikedb-api:

Set the directory in each shell where you run the examples:

export SHRIKEDB_API_DIR="$HOME/shrikedb-api"
test -f "$SHRIKEDB_API_DIR/shrikedb.v2.proto"
test -f "$SHRIKEDB_API_DIR/shrikedb.identity.v2.proto"

The server does not expose gRPC reflection. Supply -import-path and -proto as shown in each command. These files require no additional imports. Use definitions matching the server version when generating application clients.

To inspect a request type locally:

grpcurl -import-path "$SHRIKEDB_API_DIR" -proto shrikedb.v2.proto \
  describe shrikedb.v2.CypherQueryRequest

The local examples use plaintext on loopback. Configure TLS and authentication for your deployment as described in Connect To ShrikeDB.

Main Service

package shrikedb.v2;
service ShrikeDbService { ... }

The guide configures gRPC at 127.0.0.1:50251.

RPC Groups

Group RPCs

Schema and semantic mapping

CreateSchema, AddSemanticRule

KV

PutKeyValue, GetKeyValue, BulkGetKeyValue, BulkPutKeyValue

Graph writes

InsertGraphBlock, BulkInsertGraphBlocks

Query

ExecuteQuery, ExecuteSPARQL, ExecuteSPARQLUpdate, ExecuteCypher

Vector

InsertVector, BulkInsertVectors, VectorSearch, VectorSearchPacked, VectorSearchBatchPacked

Graph reads

GraphScan, BulkNeighbors, BulkNeighborsCompact

Transactions

BeginTransaction, TransactionInsertVector, TransactionInsertGraphEdge, TransactionInsertKV, TransactionInsertSpaceKey, TransactionGetKV, TransactionQuery, CommitTransaction, RollbackTransaction

Peer transaction coordination

PrepareTransactionCommit, FinalizeTransactionCommit, and ApplyTransactionCommit are server-to-server operations; applications use CommitTransaction or RollbackTransaction.

Query Requests

ExecuteQueryRequest accepts one of:

  • sparql,

  • cypher,

  • serialized_plan.

ExecuteCypher accepts:

  • query,

  • optional snapshot_version,

  • optional limit,

  • optional offset,

  • parameters.

ExecuteSPARQLUpdate accepts one update string and returns committed, operation_hash, and submitted_triples. Enable standalone default-graph INSERT DATA and DELETE DATA with SHRIKEDB_SPARQL_UPDATE_MODE=canary on the server. A request can contain several operations, including a mix of inserts and deletes, committed in order as one block. See SPARQL for examples and request limits.

Vector Search

VectorSearchRequest fields:

Field Meaning

index_name

Vector index to search.

query_vector

Query embedding.

k

Number of nearest neighbors requested.

ef_search

Optional search breadth override.

snapshot_version

Optional snapshot version.

filter

Optional entity-ID and metadata filters.

Identity Service

package shrikedb.identity.v2;
service IdentityService { ... }

The identity service requires a multi-tenant server package with authentication enabled.

RPC groups:

  • tenants: CreateTenant, GetTenant, SuspendTenant,

  • users: CreateUser, GetUser, UpdateUserStatus,

  • roles: CreateRole, GetRole,

  • policies: SetPolicyDocument, GetPolicyDocument,

  • API keys: CreateApiKey, RevokeApiKey,

  • auth: Login, RefreshToken,

  • introspection: WhoAmI.

Authentication

Identity administration and introspection authenticate the caller using one of the headers below. Login authenticates a username and password directly, and RefreshToken authenticates its refresh credential; neither requires an existing bearer token. Administrative operations require tenant Admin or Grant permission. Refresh tokens rotate: store the newly returned token and discard the old one.

Authenticated requests use:

authorization: Bearer <JWT>

or:

x-shrikedb-api-key: <key>

Legacy x-fusiondb-api-key is accepted for compatibility.