• Installation
• Quickstart
• API Reference
• Client
• Session
• Transaction
• Options
• Iterator
• Answer
• Dependencies

Installation

To use this client, you need a compatible Grakn Server running. Visit our Compatibility Table

pip install grakn-client

If multiple Python versions are available, you may wish to use

pip3 install grakn-client

Quickstart

First make sure, the Grakn server is running.

In the interpreter or in your source, import GraknClient from grakn.client.

from grakn.client import GraknClient

Instantiate a client and open a session.

from grakn.client import GraknClient

with GraknClient(uri="localhost:48555") as client:
    with client.session(keyspace="social_network") as session:
        ## session is open
        pass
    ## session is closed
## client is closed

We can also pass the credentials, as specified when configuring authentication via Grakn Console, into the client constructor as a dictionary.

client = GraknClient(uri="localhost:48555", credentials={"username": "<username>", "password": "<password>"})

Create transactions to use for reading and writing data.

from grakn.client import GraknClient

with GraknClient(uri="localhost:48555") as client:
    with client.session(keyspace="social_network") as session:
        ## creating a write transaction
        with session.transaction().write() as write_transaction:
            ## write transaction is open
            ## write transaction must always be committed (closed)
            write_transaction.commit()

        ## creating a read transaction
        with session.transaction().read() as read_transaction:
            ## read transaction is open
            ## if not using a `with` statement, we must always close the read transaction like so
            # read_transaction.close()
            pass

Running basic retrieval and insertion queries.

from grakn.client import GraknClient

with GraknClient(uri="localhost:48555") as client:
    with client.session(keyspace="social_network") as session:
        ## Insert a Person using a WRITE transaction
        with session.transaction().write() as write_transaction:
            insert_iterator = write_transaction.query('insert $x isa person, has email "x@email.com";').get()
            concepts = [ans.get("x") for ans in insert_iterator]
            print("Inserted a person with ID: {0}".format(concepts[0].id))
            ## to persist changes, write transaction must always be committed (closed)
            write_transaction.commit()

        ## Read the person using a READ only transaction
        with session.transaction().read() as read_transaction:
            answer_iterator = read_transaction.query("match $x isa person; get; limit 10;").get()

            for answer in answer_iterator:
                person = answer.map().get("x")
                print("Retrieved person with id " + person.id)

        ## Or query and consume the iterator immediately collecting all the results
        with session.transaction().read() as read_transaction:
            answer_iterator = read_transaction.query("match $x isa person; get; limit 10;").get()
            persons = [ans.get("x") for ans in answer_iterator]
            for person in persons:
                print("Retrieved person with id "+ person.id)

        ## if not using a `with` statement, then we must always close the session and the read transaction
        # read_transaction.close()
        # session.close()
        # client.close()

Check out the Concept API to learn about the available methods on the concepts retrieved as the answers to Graql queries.

To view examples of running various Graql queries using the Grakn Client Python, head over to their dedicated documentation pages as listed below.

• Insert
• Get
• Delete
• Aggregate
• Compute

API Reference

GraknClient(uri=””, credientials = {})

Client

client.session(keyspace)

client.keyspaces().retrieve()

client.keyspaces().delete(“keyspace name”)

client.close()

Session

session.transaction().read()

session.transaction().write()

session.close()

Transaction

transaction.query(query, infer=SERVER_DEFAULT, explain=SERVER_DEFAULT, batch_size=SERVER_DEFAULT)

transaction.commit()

transaction.close()

transaction.is_open()

transaction.get_concept(id)

transaction.get_schema_concept(label)

transaction.get_attributes_by_value(value, valuetype)

transaction.put_entity_type(label)

transaction.put_relation_type(label)

transaction.put_attribute_type(label)

transaction.put_role(label)

transaction.put_rule(label, when, then)

Options

The transaction query optional parameters can be used to override the default server behaviour for query processing.

The server defaults are:

• infer = True
• explain = False
• batch_size = 50

batch_size tells the server to pre-compute and stream this number of answers at a time. These are buffered in the client until read. A larger batch size causes the server to compute more answers at a time, blocking the transaction until the batch is computed. Use Transaction.Options.BATCH_ALL to retrieve all answers from the server with a single client-side request.

Iterator

Transaction queries return iterators of answers. In addition to the method below, the items in an Iterator can be consumed individually using next(iterator) method.

Answer

The type of answers contained in the iterator depends on the type of the query that has returned the iterator. The table below illustrates the answer types mapped to query types.

conceptmap.map()

conceptmap.get(var)

conceptmap.has_explanation()

conceptmap.explanation()

answer.message();

answer.number()

answer.list()

answer.set()

answer.measurement()

answer.set()

answer.owner()

answer.answers()

explanation.get_answers()

Dependencies