DOCSEARCHbyAlgolia
Submit Docs

pydgraph

repository·main·Indexed 43 days ago

https://github.com/dgraph-io/pydgraph

The official gRPC-based Python client for the Dgraph database, supporting Python 3.9 and above. It provides tools for managing DgraphClient connections, handling transactions (Txn), performing mutations and DQL queries, and executing upserts. The client supports ACLs, namespaces, and mTLS authentication, with compatibility for protobuf versions 4.23.0 through 6.x.

Tokens
21.4K
Snippets
81
Records
94
Agent score
54%

What's inside pydgraph

  1. Handle transaction conflicts with optimistic concurrency control

    main

    Dgraph uses optimistic concurrency control (MVCC). When multiple transactions modify the same data simultaneously, Dgraph aborts one of the transactions with an AbortedError. When this occurs, the entire transaction must be retried from scratch.

    pydgraph provides built-in retry utilities with exponential backoff to handle these conflicts automatically. These utilities specifically retry on:

    • pydgraph.AbortedError: Transaction conflict (optimistic concurrency).
    • pydgraph.RetriableError: Transient server errors.

    All other exceptions will propagate immediately without retrying.

  2. Quickstart with the simple example project

    main
    For an end-to-end example of using the Dgraph Python client, you can build and run the simple project located in the examples folder. Detailed instructions for this example are available in ./examples/simple/README.md.

  4. Use the Native Async/Await Client

    main

    For high-concurrency applications, use pydgraph.AsyncDgraphClient. This uses asyncio and grpc.aio for true asynchronous operations.

    Basic Async Usage

    import asyncio
import pydgraph

async def main():
    client_stub = pydgraph.AsyncDgraphClientStub('localhost:9080')
    client = pydgraph.AsyncDgraphClient(client_stub)

    try:
        await client.login("groot", "password")
        
        # Mutation
        txn = client.txn()
        await txn.mutate(set_obj={"name": "Alice"}, commit_now=True)

        # Query
        txn = client.txn(read_only=True)
        response = await txn.query('{ me(func: has(name)) { name } }')
        print(response.json)
    finally:
        await client.close()

asyncio.run(main())

    Async Connection Strings

    async with await pydgraph.async_open("dgraph://localhost:9080") as client:
    version = await client.check_version()
    print(version)

    Async Context Managers

    Both the client and transactions support async with for automatic cleanup:

    async with await pydgraph.async_open("dgraph://localhost:9080") as client:
    await client.login("groot", "password")
    async with client.txn() as txn:
        response = await txn.query('{ me(func: has(name)) { name } }')
        print(response.json)
    async with await pydgraph.async_open("dgraph://localhost:9080") as client:
    await client.login("groot", "password")
    async with client.txn() as txn:
        res = await txn.query("{ me(func: has(name)) { name } }")
        print(res.json)

  5. Run the pydgraph simple example

    main

    To run the demonstration script, follow these steps:

    1. Start Dgraph: Spin up a local Dgraph cluster using Docker Compose:

      docker compose up

      Note: The local configuration uses a blanket whitelist for security, which is suitable for local testing but should not be used in production.

    2. Execute the script: Run the sample Python code using uv:

      uv run python simple.py

    3. Cleanup: When finished, tear down the cluster with:

      docker compose down
    uv run python simple.py

  6. Clean up DgraphClientStub resources

    main

    When using manual stub management, you must close each DgraphClientStub individually to release resources.

    stub1 = pydgraph.DgraphClientStub("localhost:9080")
stub2 = pydgraph.DgraphClientStub("localhost:9081")
client = pydgraph.DgraphClient(stub1, stub2)

# ... use client

stub1.close()
stub2.close()

    Automatic Cleanup with Context Managers

    Use pydgraph.client_stub or pydgraph.DgraphClientStub as a context manager to ensure automatic release:

    # Using client_stub function
with pydgraph.client_stub("localhost:9080") as stub1:
    with pydgraph.client_stub("localhost:9081") as stub2:
        client = pydgraph.DgraphClient(stub1, stub2)
        # Use client here
    with pydgraph.client_stub("localhost:9080") as stub1:
    client = pydgraph.DgraphClient(stub1)

  7. Generate TLS certificates for Dgraph using dgraph cert

    main

    To set up mutual TLS (mTLS) for a Dgraph cluster and client, use the dgraph cert tool provided in the dgraph/dgraph Docker image. This process involves creating a Root CA, server certificates (for Alpha/Zero nodes), and client certificates (for pydgraph clients).

    1. Create the Root CA: This generates the base certificates and keys in the specified directory.
    2. Create Node Certificates: Generates node.crt and node.key for the Dgraph servers.
    3. Create Client Certificates: Generates client.user.crt and client.user.key for client authentication.

    Ensure you set appropriate file permissions (e.g., chmod +r) so the processes can read the certificates.

    # 1. Create the Root CA
docker run -t --volume $PWD/tls:/dgraph-tls dgraph/dgraph:latest dgraph cert --dir /dgraph-tls

# 2. Create Alpha server certificates (node.crt and node.key)
docker run -t --volume $PWD/tls:/dgraph-tls dgraph/dgraph:latest dgraph cert --nodes localhost --dir /dgraph-tls

# 3. Create client certificates (client.user.crt and client.user.key)
docker run -t --volume $PWD/tls:/dgraph-tls dgraph/dgraph:latest dgraph cert --client user --dir /dgraph-tls

# Set permissions
sudo chmod +r tls/*

  9. Run pydgraph Jupyter Notebook examples

    main

    You can run the provided Jupyter notebooks either locally or in a cloud environment like Google Colab. These notebooks demonstrate advanced usage patterns, such as integrating Dgraph with LLMs and OpenAI embeddings for AI classification tasks.

    https://colab.google/

  10. Connect using Dgraph connection strings

    main

    pydgraph supports connection strings in the format: dgraph://{username:password@}host:port?args.

    Connection String Arguments

    ArgValueDescription
    bearertoken<token>An access token
    sslmodedisablerequire
    namespace<namespace>An integer-based namespace (requires username/password)

    Examples

    • dgraph://localhost:9080 (No ACL, no TLS)
    • dgraph://sally:supersecret@dg.example.com:443?sslmode=verify-ca (ACL + TLS with CA verification)
    • dgraph://foo-bar.grpc.dgraph-io.com:443?sslmode=verify-ca&bearertoken=<token> (Secure gateway)
    • dgraph://sally:supersecret@dg.example.com:443?namespace=2 (ACL in namespace 2)

    Using pydgraph.open

    To open a connection using a string:

    client = pydgraph.open("dgraph://groot:password@localhost:8090")
# ... use client
client.close()
    client = pydgraph.open("dgraph://groot:password@localhost:8090")

  11. Install uv for dependency management

    main

    This project uses uv to manage dependencies and virtual environments. You can install it using one of the following methods depending on your operating system:

    macOS/Linux:

    curl -LsSf https://astral.sh/uv/install.sh | sh

    Windows:

    powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

    Using pip:

    pip install uv
    pip install uv

  12. ⚠️ Deprecated: Dgraph Cloud AI Classification Example

    main

    This notebook demonstrates an experimental workflow using Dgraph, LLMs, and OpenAI embeddings.

    WARNING: This example uses deprecated Dgraph Cloud features (Lambda functions, cloud authentication, cerebro API) and will not function with current Dgraph deployments. For current examples, visit https://dgraph.io/docs.

    Historically, this workflow involved:

    1. Creating a GraphQL schema.
    2. Deploying a JavaScript Lambda function to a Dgraph Cloud endpoint.
    3. Using the Lambda to intercept mutations, call OpenAI for embeddings, and perform vector similarity calculations to automatically categorize data.
    4. Storing embeddings and similarity facets in Dgraph.