×  

tina4-ultipa

The Ultipa graph driver for Python

A full-fidelity gRPC client for the Ultipa graph database — every GQL type decoded, no Tina4 lock-in.

Quick Start • Type Support • Ultipa Docs • Protocol • tina4.com

A thin, standalone gRPC driver for the Ultipa graph database (ultipa-gqldb). It is the Ultipa driver behind Tina4's graph data layer — but has no Tina4 dependency and is perfectly usable on its own. Tina4's core stays zero-dependency; this driver is an optional package loaded only for ultipa:// connections, speaking gRPC directly through grpcio — with no protobuf runtime dependency. This package's own hand-rolled proto3 codec (src/tina4_ultipa/_pb.py) covers the 8 gqldb messages we consume, so pip install never drags in protobuf and its version churn.

Ultipa is a high-performance graph database with a GQL (ISO/IEC 39075) query surface. Learn more at ultipa.com · docs at ultipa.com/docs.

Why this driver

• Complete value decoding. Every gqldb PropertyType is decoded to a natural Python value — including the composites and temporals most thin clients skip (see Type support).
• Real gRPC, no protobuf runtime. Uses grpcio for HTTP/2 + gRPC framing, and this package's own hand-rolled proto3 codec (src/tina4_ultipa/_pb.py) for the payloads — so pip install never drags in protobuf and its version churn, and there is no protoc reflection round-trip or codegen step at install time.
• Fails loud. A bad statement raises; it never returns a falsy value you might miss. An unreachable host raises within your connect_timeout.
• Cross-language parity. The same driver exists for Python, Node.js, Ruby and PHP, decoding byte-for-byte identically.

Install

pip install tina4-ultipa

Quick start

from tina4_ultipa import UltipaClient

# from a URL...
db = UltipaClient.from_url("ultipa://admin:password@localhost:60061/mygraph")
# ...or explicitly
db = UltipaClient("localhost", 60061, username="admin", password="password", graph="mygraph")

# read — GQL text + optional named params
for row in db.query("MATCH (n:Person) WHERE n.age > $min RETURN n.name AS name",
                    params={"min": 21}):
    print(row["name"])

# write — dml stats on success, raises on a bad statement
r = db.execute("INSERT (:Person {name: 'Alice', age: 30})")
print(r.dml_stats["inserted_nodes"])   # 1

db.close()

query() runs a read, execute() a write — both take GQL and optional params and return an UltipaResult:

Errors: a bad statement raises UltipaError; an unreachable host raises UltipaConnectError within connect_timeout, naming host, port and elapsed time.

Type support

Every gqldb PropertyType decodes to a natural Python value:

Node/edge dicts include the 8-byte internal-id (uuid) trailer emitted by gqldb 6.1.147+.

Protocol

ultipa-gqldb speaks gRPC (default port 60061, protobuf package gqldb). The driver authenticates with SessionService.Login, passes the returned session_id on every call as the session-id metadata header (as an unsigned decimal), then runs QueryService.Gql. Each value is a TypedValue{type, bytes}; all multi-byte integers are little-endian. The full byte-level encoding is documented in PROTOCOL.md — grounded in Ultipa's official gqldb SDK and proto, and verified live against gqldb-grpc 6.2.130 CE.

Sample data pack

Get a real graph into your community-edition instance in seconds — 10 people (with photos), 3 companies, 3 projects, 5 skills and 62 relationships:

python examples/seed.py ultipa://admin:PASSWORD@HOST:60061
# graph defaults to "default"; override with TINA4_ULTIPA_GRAPH

Then explore it:

MATCH (n:Person)-[e]->(m) RETURN n, e, m LIMIT 100
RETURN db.overview()

The pack lives in examples/ — people.json describes the graph and sample_data/faces/*.jpg are 64px portraits of AI-generated, non-existent people (thispersondoesnotexist.com) stored as BLOB properties, so it also demonstrates binary round-tripping through gqldb. Re-running is safe — it clears the demo labels (Person/Company/Project/Skill) first.

Testing

Real, no-mock tests run against a live server:

TINA4_TEST_ULTIPA_URL=ultipa://admin:password@host:60061 python tests/test_driver.py

They cover scalars, node/edge/list/map decoding, the full temporal/spatial/interval set, path decoding, and a BLOB image round-trip.

Links

• Ultipa — website ultipa.com · docs ultipa.com/docs · GQL query language reference in the docs
• Tina4 — tina4.com · the framework this driver powers
• This driver — github.com/tina4stack/ultipa-python · sibling drivers for Node.js, Ruby, PHP

License

MIT. Note: the Ultipa community-edition server is licensed by Ultipa for personal / non-commercial use — review Ultipa's terms before you deploy it. This driver is an independent client and may not be officially supported by Ultipa.

Sponsored by Code Infinity · part of the Tina4 stack.