llama-index-spanner 0.1.5

LlamaIndex integrations for Google Cloud Spanner

Spanner for LlamaIndex

• Client Library Documentation
• Product Documentation

Quick Start

In order to use this library, you first need to go through the following steps:

1. Select or create a Cloud Platform project.
2. Enable billing for your project.
3. Enable the Google Cloud Spanner API.
4. Setup Authentication.

Installation

Install this library in a virtualenv using pip. virtualenv is a tool to create isolated Python environments. The basic problem it addresses is one of dependencies and versions, and indirectly permissions.

With virtualenv, it’s possible to install this library without needing system install permissions, and without clashing with the installed system dependencies.

Supported Python Versions

Python >= 3.9

Mac/Linux

pip install virtualenv
virtualenv <your-env>
source <your-env>/bin/activate
<your-env>/bin/pip install llama-index-spanner

Windows

pip install virtualenv
virtualenv <your-env>
<your-env>\Scripts\activate
<your-env>\Scripts\pip.exe install llama-index-spanner

Spanner Property Graph Store Usage

Use SpannerPropertyGraphStore to store nodes and edges extracted from documents.

from llama_index_spanner import SpannerPropertyGraphStore

graph_store = SpannerPropertyGraphStore(
    instance_id="my-instance",
    database_id="my-database",
    graph_name="my_graph",
)

See the full Spanner Graph Store tutorial.

Spanner Graph Retrievers Usage

Use SpannerGraphTextToGQLRetriever to translate natural language question to GQL and query SpannerPropertyGraphStore.

from llama_index_spanner import (
    SpannerPropertyGraphStore,
    SpannerGraphTextToGQLRetriever,
)
from llama_index.llms.google_genai import GoogleGenAI

graph_store = SpannerPropertyGraphStore(
    instance_id="my-instance",
    database_id="my-database",
    graph_name="my_graph",
)
llm = GoogleGenAI(
    model="gemini-2.0-flash",
)
retriever = SpannerGraphTextToGQLRetriever(graph_store=graph_store, llm=llm)
retriever.retrieve("Where does Elias Thorne's sibling live?")

Use SpannerGraphCustomRetriever to query your SpannerPropertyGraphStore with a hybrid retrieval approach, combining natural language-to-GQL translation with vector search capabilities.

The Vector Context Retriever uses semantic vector search to surface relevant contexts, even when they aren't explicitly structured in the graph. The Text2GQL Retriever translates natural language into GQL queries to extract precise relationships and attributes from the property graph.

The results from both retrievers are evaluated using an LLM-based reranker, which scores them based on relevance, completeness, and contextual fit with the original query.

This hybrid + rerank pipeline enables the system to handle everything from vague, open-ended questions to structured, entity-specific queries, delivering high-confidence, context-aware responses.

from llama_index_spanner import SpannerPropertyGraphStore, SpannerGraphCustomRetriever
from llama_index.llms.google_genai import GoogleGenAI
from llama_index.embeddings.google_genai import GoogleGenAIEmbedding

graph_store = SpannerPropertyGraphStore(
    instance_id="my-instance",
    database_id="my-database",
    graph_name="my_graph",
)
llm = GoogleGenAI(
    model="gemini-2.0-flash",
)
embed_model = GoogleGenAIEmbedding(model_name="text-embedding-004")
retriever = SpannerGraphCustomRetriever(
    similarity_top_k=4,
    path_depth=2,
    graph_store=graph_store,
    llm_text_to_gql=llm,
    embed_model=embed_model,
    llmranker_top_n=3,
)
retriever.retriever("Who lives in desert?")

See the full Spanner Graph Retrievers tutorial.

Contributing

Contributions to this library are always welcome and highly encouraged.

See CONTRIBUTING for more information how to get started.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. See Code of Conduct for more information.

License

Apache 2.0 - See LICENSE for more information.