Connect an application
Run a read-only query using the HTTP API, a Bolt driver, or a Gremlin WebSocket client.
On this page
Prepare an application identity
- Publish the target model and note its ID. The code below uses
graphfrom the sample. - In Access Control, create a dedicated service account, such as
analytics. Generate its token withopenssl rand -hex 32and assign a role with query permission for that model. See Users and permissions. - Set
GRAPHLAKE_TOKENin the client process from your secret store. SetGRAPHLAKE_ORIGINto the service’s HTTPS origin. For the local sample, usehttp://127.0.0.1:7347.
Run a revision-pinned HTTP query
Save the following Python 3 script and run it with the client’s environment. It discovers the model’s active_revision, then sends a unique request ID, the chosen revision, and the query. parameters_json is a JSON string containing the Cypher parameters.
import base64
import json
import os
import uuid
from urllib.parse import quote
from urllib.request import Request, urlopen
origin = os.environ["GRAPHLAKE_ORIGIN"].rstrip("/")
model_id = os.environ.get("GRAPHLAKE_MODEL", "graph")
credentials = "svc/analytics:" + os.environ["GRAPHLAKE_TOKEN"]
basic = base64.b64encode(credentials.encode()).decode()
def call(path, body=None):
headers = {"Authorization": "Basic " + basic}
data = None
if body is not None:
headers.update({"Content-Type": "application/json", "Origin": origin})
data = json.dumps(body).encode()
with urlopen(Request(origin + "/api/v1" + path, data, headers), timeout=15) as response:
return json.load(response)
models = call("/models")
model = next(model for model in models if model["id"] == model_id)
result = call("/models/" + quote(model_id, safe="") + "/query", {
"request_id": str(uuid.uuid4()),
"model_revision": model["active_revision"],
"language": "cypher",
"query": "MATCH (a:Account) WHERE a.id = $id RETURN a.name AS account",
"parameters_json": json.dumps({"id": 1}),
"timeout_ms": 10000,
})
print(result["rows"])
Expected result [['Alice']] for the sample. HTTP preview rows represent cells as strings or null. The response also reports the model revision, source information, and whether the preview is truncated.
For full results, grant export in addition to query. Request capture_result: true, check snapshot_complete, and fetch GET /api/v1/models/{id}/results/{snapshot} while the snapshot is available.
Read through a Bolt driver
Set --driver-model graph --bolt-port 7687 on the service to enable Bolt and expose it through TLS as shown in the client configuration. Use a direct bolt+s:// URI in production and select the published model with the driver’s database argument.
import os
from neo4j import GraphDatabase
auth = ("svc/analytics", os.environ["GRAPHLAKE_TOKEN"])
with GraphDatabase.driver("bolt+s://graphlake.example:7687", auth=auth) as driver:
with driver.session(database="graph") as session:
records = session.run("MATCH (a:Account) RETURN a.name AS name ORDER BY name")
print([record["name"] for record in records])The release’s driver checks use neo4j==5.28.2. Auto-commit is available across supported sources. Explicit read transactions are supported for PostgreSQL and Parquet. Select compatible client versions from the protocol reference for your release.
Read through Gremlin WebSocket
Set --driver-model graph on the service to enable Gremlin and set its default model. Forward WebSocket upgrades on /gremlin through your HTTPS proxy. The traversal source name can select an authorized model.
import os
from gremlin_python.driver.driver_remote_connection import DriverRemoteConnection
from gremlin_python.driver.serializer import GraphSONSerializersV3d0
from gremlin_python.process.anonymous_traversal import traversal
conn = DriverRemoteConnection(
"wss://graphlake.example/gremlin",
"graph",
username="svc/analytics",
password=os.environ["GRAPHLAKE_TOKEN"],
message_serializer=GraphSONSerializersV3d0(),
)
try:
g = traversal().with_remote(conn)
print(g.V().hasLabel("Account").values("name").order().to_list())
finally:
conn.close()Use gremlinpython==3.7.4 for this example. It prints Alice, Bob, and Carol. Use supported read-only traversals and a GraphSON 3 or GraphBinary 1.0 serializer.
Handle revisions and access failures
If a model was republished after discovery, reload the active revision and reissue the read with a new request ID once you have confirmed that the new mapping is acceptable. For 401, check the account name and token. For 403, check the model role and tenant scope. Investigate readiness and source errors before retrying long queries.
For AI clients use MCP. For readiness and source failures see Troubleshooting.