Installation#

Requirements#

  • Python 3.11–3.14. On Python 3.10, pip installs 0.2.0 instead, without an error, and these pages do not describe it.

  • A running AgensGraph 2.17 or later. The driver refuses an older server when it connects.

  • The pgvector extension (for vector search and entity embeddings)

  • LlamaIndex itself (llama-index)

The integration depends on llama-index-core (0.12–0.14), the agensgraph-python 2.0 driver, and psycopg[binary] 3.3.4 or later. All three are installed with it.

Install#

pip install llama-index llama-index-agensgraph

Or through the agensgraph-ai umbrella package, which installs the same thing:

pip install llama-index "agensgraph-ai[llama-index]"

This documentation covers 0.3.1. 0.3.1 is a documentation release; its code is 0.3.0’s. The examples that call a model use OpenAI, so they also need llama-index-llms-openai and llama-index-embeddings-openai (both come with llama-index) and OPENAI_API_KEY.

Upgrading from 0.1 or 0.2. Those versions kept every node on the single "__Node__" label, with the type in a labels property. 0.3 cannot read that layout: every node comes back labelled __Node__, MATCH (n:"Person") finds nothing, and upserting an existing entity writes a second copy. Upgrade with pip install -U llama-index-agensgraph, then drop the graph and ingest again with 0.3. Vector-store graphs need no change. Two smaller changes: pass string parameters to structured_query as a plain str, because a json.dumps’d value now matches nothing; and AgensQueryException.details now carries the server’s message (0.2 raised it under a detail key, so details read "unknown").

Set up the pgvector extension#

AgensGraph does not bundle pgvector. Build it once against your AgensGraph install and enable it in your database:

git clone https://github.com/pgvector/pgvector.git
export PG_CONFIG=/path/to/agens/bin/pg_config
cd pgvector && make && make install

-- in your AgensGraph database:
CREATE EXTENSION IF NOT EXISTS vector;

The stores also run CREATE EXTENSION IF NOT EXISTS vector themselves: the vector store always, and the property graph store when it is given a vector_dimension. Creating the extension needs a privileged role, so create it beforehand as a superuser, as above, when the stores connect as an ordinary role. If the extension is missing and cannot be created, the vector store raises ValueError("Vector extension not supported ..."). The property graph store only logs a warning, and from then on vector_query returns no results. No functions or tables of the package’s own are installed; the graph store reads the schema from the catalogs.

Connecting#

Connect the stores as an application role rather than a superuser. SafeTextToCypherRetriever refuses a superuser or a member of pg_execute_server_program unless allow_server_programs=True (see Usage). As a superuser, after creating the vector extension:

CREATE ROLE app LOGIN PASSWORD 'app';
GRANT CREATE ON DATABASE mydb TO app;   -- lets the stores create their graphs

The property graph store takes a conf dictionary of psycopg connection keyword arguments, passed to the driver’s Connection.connect:

conf = {
    "dbname": "mydb",
    "user": "app",
    "password": "app",
    "host": "localhost",
    "port": 5432,
}

The vector store takes a libpq url such as postgresql://user:password@localhost:5432/mydb. Both stores accept a vector_dimension (graph store) / embedding_dimension (vector store) that must match your embedding model — 1536 for OpenAI text-embedding-3-small, for example. Settings the connection leaves out, such as the password, are read from the standard libpq environment variables (PGPASSWORD and the like).

Opening a store is enough to check the connection. Each store creates its graph if it does not exist yet:

from llama_index_agensgraph.graph_stores.agensgraph import AgensPropertyGraphStore
from llama_index_agensgraph.vector_stores.agensgraph import AgensgraphVectorStore

graph_store = AgensPropertyGraphStore(graph_name="li_kg", conf=conf, vector_dimension=1536)
vector_store = AgensgraphVectorStore(
    url="postgresql://app:app@localhost:5432/mydb", embedding_dimension=1536
)
print(graph_store.structured_query("RETURN 1 AS ok"))

Each store holds one connection of its own. To share a pool across stores, pass engine=AgensEngine.from_url(...) or engine=AgensEngine.from_conf(conf) to both; see Usage for that and for full examples. statement_timeout= (in seconds) on the graph store or on AgensEngine limits every statement they run.