pydgraph

This is the official Dgraph database client implementation for Python (Python >= v3.9), using gRPC.

Before using this client, we highly recommend that you read the the product documentation at https://docs.dgraph.io/.

pydgraph

Install

Install using pip:

pip install pydgraph

Protobuf Version Compatibility

pydgraph supports protobuf versions 4.23.0 through 6.x. The specific version installed depends on your environment:

Modern environments: protobuf 6.x is recommended and will be installed by default on Python 3.13+
Legacy environments: If you need to use protobuf 4.x or 5.x (e.g., for compatibility with other packages), you can pin the version:

# For protobuf 4.x compatibility
pip install pydgraph "protobuf>=4.23.0,<5.0.0"

# For protobuf 5.x compatibility
pip install pydgraph "protobuf>=5.0.0,<6.0.0"

All supported protobuf versions are tested in CI against both Dgraph latest and Dgraph HEAD.

Supported Versions

Depending on the version of Dgraph that you are connecting to, you should use a different version of this client. Using an incompatible version may lead to unexpected behavior or errors.

| Dgraph version | pydgraph version | | :------------: | :--------------: | | 21.03.x | 21.03.x | | 23.0.x+ | 23.0.x | | 24.0.x+ | 24.0.x | | 25.0.x+ | 25.0.x |

Quickstart

Build and run the simple project in the examples folder, which contains an end-to-end example of using the Dgraph python client. For additional details, follow the instructions in the project's README.

Using a client

Creating a Client

You can initialize a DgraphClient object by passing it a list of DgraphClientStub clients as variadic arguments. Connecting to multiple Dgraph servers in the same cluster allows for better distribution of workload.

The following code snippet shows just one connection.

import pydgraph

client_stub = pydgraph.DgraphClientStub('localhost:9080')
client = pydgraph.DgraphClient(client_stub)

Using Dgraph Connection Strings

The pydgraph package supports connecting to a Dgraph cluster using connection strings. Dgraph connections strings take the form dgraph://{username:password@}host:port?args.

username and password are optional. If username is provided, a password must also be present. If supplied, these credentials are used to log into a Dgraph cluster through the ACL mechanism.

Valid connection string args:

| Arg | Value | Description | | ----------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | bearertoken | <token> | an access token | | sslmode | disable | require | verify-ca | TLS option, the default is disable. If verify-ca is set, the TLS certificate configured in the Dgraph cluster must be from a valid certificate authority. | | namespace | <namespace> | a previously created integer-based namespace, username and password must be supplied |

Note the sslmode=require pair is not supported and will throw an Exception if used. Python grpc does not support traffic over TLS that does not fully verify the certificate and domain. Developers should use the existing stub/client initialization steps for self-signed certs as demonstrated in examples/tls/tls_example.py.

Some example connection strings:

| Value | Explanation | | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | dgraph://localhost:9080 | Connect to localhost, no ACL, no TLS | | dgraph://sally:supersecret@dg.example.com:443?sslmode=verify-ca | Connect to remote server, use ACL and require TLS and a valid certificate from a CA | | dgraph://foo-bar.grpc.dgraph-io.com:443?sslmode=verify-ca&bearertoken=<some access token> | Connect to a Dgraph cluster protected by a secure gateway | | dgraph://sally:supersecret@dg.example.com:443?namespace=2 | Connect to a ACL enabled Dgraph cluster in namespace 2 |

Using the Open function with a connection string:

# open a connection to an ACL-enabled, non-TLS cluster and login as groot
client = pydgraph.open("dgraph://groot:password@localhost:8090")

# Use the client
...

client.close()

Login into a Namespace

If your server has Access Control Lists enabled (Dgraph v1.1 or above), the client must be logged in for accessing data. If you didn't use the open function with credentials and a namespace, use the login endpoint.

Calling login will obtain and remember the access and refresh JWT tokens. All subsequent operations via the logged in client will send along the stored access token.

client.login("groot", "password")

If your server additionally has namespaces (Dgraph v21.03 or above), use the login_into_namespace API.

client.login_into_namespace("groot", "password", "123")

Altering the Database

Set the Dgraph types schema

To set the Dgraph types schema (aka DQL schema), create an Operation object, set the schema and pass it to DgraphClient#alter(Operation) method.

schema = 'name: string @index(exact) .'
op = pydgraph.Operation(schema=schema)
client.alter(op)

Indexes can be computed in the background. You can set the run_in_background field of pydgraph.Operation to True before passing it to the Alter function. You can find more details in the Dgraph documentation on background indexes.

Note To deploy the GraphQL schema in python you have to use GraphQL client such as python-graphql-client to invoke the GraphQL admin mutation updateGQLSchema

schema = 'name: string @index(exact) .'
op = pydgraph.Operation(schema=schema, run_in_background=True)
client.alter(op)

Drop data

To drop all data and schema:

# Drop all data including schema from the Dgraph instance. This is a useful
# for small examples such as this since it puts Dgraph into a clean state.
op = pydgraph.Operation(drop_all=True)
client.alter(op)

Note If the Dgraph cluster contains a GraphQL Schema, it will also be deleted by this operation.

To drop all data and preserve the DQL schema:

# Drop all data from the Dgraph instance. Keep the DQL Schema.
op = pydgraph.Operation(drop_op="DATA")
client.alter(op)

To drop a predicate:

# Drop the data associated to a predicate and the predicate from the schema.
op = pydgraph.Operation(drop_op="ATTR", drop_value="<predicate_name>")
client.alter(op)

the same result is obtained using

# Drop the data associated to a predicate and the predicate from the schema.
op = pydgraph.Operation(drop_attr="<predicate_name>")
client.alter(op)

To drop a type definition from DQL Schema:

# Drop a type from the schema.
op = pydgraph.Operation(drop_op="TYPE", drop_value="<predicate_name>")
client.alter(op)

Note drop_op="TYPE" just removes a type definition from the DQL schema. No data is removed from the cluster. The operation does not drop the predicates associated with the typ

Pydgraph

Install / Use

README