AgensGraph for Python
=====================

``agensgraph-python`` reads and writes an `AgensGraph <https://tech.skaiworldwide.com/docs/en/agensgraph/18/>`_
graph from Python, in blocking or ``asyncio`` code. It is built on `psycopg 3 <https://www.psycopg.org/psycopg3/>`_:
a connection is a psycopg connection, so cursors, ``COPY``, pipelines, ``LISTEN`` and two-phase commit
keep working, and Cypher and SQL run on the same connection, in the same transaction.

.. code-block:: console

   $ pip install agensgraph-python

.. code-block:: python

   import agensgraph

   with agensgraph.connect("host=localhost dbname=docs user=agens") as conn:
       conn.graph("moviekb")
       result = conn.execute_query(
           "MATCH (p:person)-[:acted_in]->(m:movie {title: %s}) RETURN p",
           ("The Matrix",),
       )
       for (person,) in result.records:
           print(person.properties["name"])

A vertex, an edge and a path arrive as ``Vertex``, ``Edge`` and ``Path`` values, not as text to parse.
Python 3.11 or later; AgensGraph 2.17 or later.

What it does
------------

- **Graph values** in both of the server's renderings, hashable and compared on identity, with each
  property map decoded only when it is read.
- **Parameters that mean what they say**: a string is sent as ``text``, a ``dict`` as a property map,
  and a value that would be read the wrong way is refused before it is sent.
- **Bulk loading** with binary ``COPY``, and **upserts** that write only what is not already there.
- **Arrow, pandas and polars** export, from the bytes on the wire, and loading from a DataFrame.
- **Embedding vectors** through pgvector, with index and search built to agree.
- **Schema inspection and declaration**: read what a graph holds, and reconcile it with what it should.
- **Pools, deadlines and retries** for a service: one budget for the wait and the statement, a
  pool that retires every connection after a restart, and failures classified by what to do next.
- **Untrusted statements**, such as a language model's query, run so that the server refuses every write.

Where to go next
----------------

.. grid:: 1 2 2 3
   :gutter: 3

   .. grid-item-card:: Get started
      :link: get_started/index
      :link-type: doc

      Install the driver, connect, and read and write the example graph.

   .. grid-item-card:: Using the driver
      :link: guide/index
      :link-type: doc

      Connecting, running statements, parameters, graph values and transactions.

   .. grid-item-card:: Working with data
      :link: data/index
      :link-type: doc

      Bulk loading, DataFrames and Arrow, embedding vectors, and notifications.

   .. grid-item-card:: Schema
      :link: schema/index
      :link-type: doc

      Inspecting a graph's catalogs, and declaring the labels, indexes and constraints it needs.

   .. grid-item-card:: Running in production
      :link: production/index
      :link-type: doc

      Pooling, timeouts, retries, untrusted statements, errors and observability.

   .. grid-item-card:: Reference
      :link: reference/index
      :link-type: doc

      Every class and function, server compatibility, and the changelog.

Every example in this manual runs against the AgensGraph manual's
`example dataset <https://tech.skaiworldwide.com/docs/en/agensgraph/18/get_started/example-dataset.html>`_,
a small graph of films and the people who made them, and is checked against a live server.

.. toctree::
   :hidden:

   get_started/index
   guide/index
   data/index
   schema/index
   production/index
   reference/index