Connect To ShrikeDB

The gRPC examples require the downloadable API definitions and SHRIKEDB_API_DIR setup. ShrikeDB exposes three practical surfaces: gRPC, HTTP, and admin health.

Connection Map

Surface Default Use it for Tool

gRPC

127.0.0.1:50251

Database reads/writes and queries.

grpcurl, generated clients.

HTTP

http://127.0.0.1:8182

Convenience REST calls and admin reports.

curl, browser, HTTP client.

Admin health

http://127.0.0.1:9190

Liveness, readiness, startup, and health diagnostics.

curl, Kubernetes probes.

gRPC Service Names

Use the ShrikeDB v2 database service for data operations. Use the ShrikeDB v2 identity service for multi-tenant identity and access management:

shrikedb.v2.ShrikeDbService
shrikedb.identity.v2.IdentityService

Use those service names when calling with grpcurl.

First Health Check

curl http://127.0.0.1:9190/health/ready

First Cypher Call

grpcurl -plaintext \
  -import-path "$SHRIKEDB_API_DIR" -proto shrikedb.v2.proto \
  -d '{"query":"MATCH (n) RETURN n LIMIT 5"}' \
  127.0.0.1:50251 shrikedb.v2.ShrikeDbService/ExecuteCypher

First Direct Vector Call

grpcurl -plaintext \
  -import-path "$SHRIKEDB_API_DIR" -proto shrikedb.v2.proto \
  -d '{
    "indexName": "demo_vec",
    "queryVector": [0.10, 0.20, 0.30, 0.40],
    "k": 3,
    "efSearch": 64
  }' \
  127.0.0.1:50251 shrikedb.v2.ShrikeDbService/VectorSearchPacked

Create and populate demo_vec with four-dimensional vectors before this call. An absent index, mismatched dimension, or invalid vector can produce an error. The complete write/search sequence is in Your first multimodal dataset.

First HTTP Call

curl http://127.0.0.1:8182/api/v1/admin/kv/namespaces

Select a database

The default database is used when no selector is supplied. List available databases with the CLI’s databases command, then use open database <id>, or add x-shrikedb-database: <id> to HTTP and gRPC requests. Use a logical ID returned by the server, not a filesystem path.

In grpcurl, add -H "x-shrikedb-database: YOUR_DATABASE_ID". In curl, use the same header. Apply it consistently to writes, reads, and queries in a workflow.

Read query results

ExecuteCypher and ExecuteSPARQL return streams of QueryResultRow messages. Each row contains bindings, a map from output column name to a typed value. Packed vector search returns parallel identifier and score arrays. Preserve identifier values as 64-bit integers or strings in your application.

Add Authentication

If the server is running with multi-tenant auth, add one of these headers.

JWT:

grpcurl -plaintext \
  -import-path "$SHRIKEDB_API_DIR" -proto shrikedb.v2.proto \
  -H "authorization: Bearer ${SHRIKEDB_ACCESS_TOKEN}" \
  -d '{"query":"MATCH (n) RETURN n LIMIT 5"}' \
  127.0.0.1:50251 shrikedb.v2.ShrikeDbService/ExecuteCypher

API key:

grpcurl -plaintext \
  -import-path "$SHRIKEDB_API_DIR" -proto shrikedb.v2.proto \
  -H "x-shrikedb-api-key: ${SHRIKEDB_API_KEY}" \
  -d '{"query":"MATCH (n) RETURN n LIMIT 5"}' \
  127.0.0.1:50251 shrikedb.v2.ShrikeDbService/ExecuteCypher

Connection Troubleshooting

Symptom Likely cause Try

connection refused

Server is not listening or port mapping is wrong.

Check curl /health/live and container -p flags.

unknown service shrikedb.v2.ShrikeDbService

Wrong endpoint or a non-gRPC port.

Use port 50251, not HTTP/admin ports.

unauthenticated

Auth is enabled.

Add authorization or x-shrikedb-api-key.

Empty query result

Database is empty or the pattern does not match.

Load the sample records in Your first multimodal dataset.