Skip to main content

Ultipa Python Driver

Official Python driver for Ultipa graph database (GQL).

Requirements

  • Python 3.10+

Installation

pip install ultipa          # base driver
pip install ultipa[ml]      # + graph ML data loaders (torch); see gqldb.ml

Note: This is the v6.x driver for Ultipa Graph. If you are using Ultipa v4.x, please install ultipa==4.5.2. If you are using Ultipa v5.x, please install ultipa==5.2.1.

Quick Start

from gqldb import GqldbClient
from gqldb.config import GqldbConfig

# Create client
config = GqldbConfig(
    hosts=["localhost:60061"],
    username="admin",
    password="password",
    default_graph="myGraph"
)
client = GqldbClient(config)
client.login("admin", "password")

# Execute query
response = client.gql("MATCH (n) RETURN n LIMIT 10")

print(f"Rows: {len(response.rows)}")
print(f"Columns: {response.columns}")

# Close
client.close()

Features

  • GQL query execution with parameters
  • Streaming results for large datasets
  • Transaction support (begin, commit, rollback)
  • Graph management (create, drop, list)
  • Bulk import for high-throughput loading
  • Algorithm support (CALL algo.pagerank, algo.degree, etc.)
  • Graph ML data loaders for PyTorch Geometric / DGL — gqldb.ml (GraphLoader, NeighborLoader, EdgeLoader)
  • Type hints support
  • Health checks

Errors

Every driver error is a GqldbError. An error from the server carries the engine's error code in e.code (for example 5020) and a stable name in e.reason (for example "FULLTEXT_INDEX_LOADING"); both are 0 and "" when the server sent none. They come from a structured detail on the gRPC error, never from the message text. EngineCode and ErrorReason name the common ones, and error_detail(exc) reads them from any exception.

from gqldb import GqldbError, EngineCode

try:
    client.gql("INSERT (:Person {name: 'Alice'})")
except GqldbError as e:
    if e.code == EngineCode.WRITES_COMMITTED:
        pass  # stored although the call failed: do not run it again

A gql / gql_stream call with QueryConfig(read_only=True) and no transaction_id is sent again when the server answers 5020 (a fulltext index is still loading): up to retry_count times (default 3), waiting retry_delay (default 0.1 s) and doubling, capped at 2 s, all within the call's timeout. retry_count=0 turns it off. After signing in again, or when a result is too large for gql, a call is sent again only if the server refused it before it ran or it is read_only outside a transaction: a request that may have written is never sent again. An answer marked partly stored (partly_stored(e): a statement failed after earlier statements of the request had committed, or a [5024] answer) is never sent again, a 5020 included; never run such a request again as it is. A write conflict (3011, WriteConflictError: nothing stored) is never sent again, with or without a transaction_id: run the whole transaction again yourself, or let with_transaction(..., retry_on_conflict=N) do it. See GUIDE.md.

Documentation

See Quick Start for detailed usage.

For the graph ML data loaders (streaming features / subgraphs into PyTorch Geometric / DGL for GNN training), see gqldb/ml/README.md.

License

MIT License

Metadata

Release files for ultipa 6.2.15

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ultipa 6.2.15
File Size Uploaded Provenance Actions
ultipa-6.2.15.tar.gz 209.0 kB Without provenance Details for ultipa-6.2.15.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ultipa 6.2.15
File Interpreter ABI Platform Actions
ultipa-6.2.15-py3-none-any.whl Python 3 none any Details for ultipa-6.2.15-py3-none-any.whl

Total release size: 453.7 kB

Release files / ultipa-6.2.15.tar.gz

Download URL ultipa-6.2.15.tar.gz
Size 209.0 kB
Tags Source
SHA-256 checksum
How to use checksums
a4dbd6c1c24f2d4898df3ae012b01a60173f9bde0b7789b1e7d34b9a7b4c0c1b
BLAKE2b-256 checksum
How to use checksums
ddb4a73de39394abe5c0078a1acb8ad677c985d0f544e40733cc64dba9731a09
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.14

Release files / ultipa-6.2.15-py3-none-any.whl

Download URL ultipa-6.2.15-py3-none-any.whl
Size 244.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6a53d726333ab6f7e3736bbc0c0764213ad910e2477ae2c4e76cb1a2fd463c02
BLAKE2b-256 checksum
How to use checksums
f8fd2926a89d14e112f91d85b5542f943dde362e31de602290d76ad0b9cad25d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.14

Security for ultipa 6.2.15

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

6.2.15 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page