Spanner Plugin#

class graphistry.plugins.spanner.SpannerMixin(*args, **kwargs)#

Bases: Plottable

SpannerMixin is a Graphistry Mixin that allows you to plot data from Spanner.

static add_type_from_label_to_df(df)#

Add ‘type’ column from ‘label’ for Graphistry type handling.

Creates a ‘type’ column from the ‘label’ column for proper visualization in Graphistry. If a ‘type’ column already exists, it is renamed to ‘type_’ before creating the new ‘type’ column.

Parameters:: df (pd.DataFrame) – DataFrame containing node or edge data with ‘label’ column
Returns:: Modified DataFrame with the updated ‘type’ column
Return type:: pd.DataFrame

configure_spanner(instance_id, database_id, project_id=None, credentials_file=None)#

Configure Google Cloud Spanner connection settings.

Sets up the connection parameters for accessing a Spanner database instance. Either project_id or credentials_file must be provided for authentication.

Parameters:

instance_id (str) – The Spanner instance identifier
database_id (str) – The Spanner database identifier
project_id (Optional[str]) – Google Cloud project ID (optional if using credentials_file)
credentials_file (Optional[str]) – Path to service account credentials JSON file

Returns:

Self for method chaining

Return type:

Plottable

Raises:

ValueError – If neither credentials_file nor project_id is provided

Example: Using project ID

import graphistry
g = graphistry.configure_spanner(
    project_id="my-project",
    instance_id="my-instance", 
    database_id="my-database"
)

Example: Using service account credentials

import graphistry
g = graphistry.configure_spanner(
    instance_id="my-instance",
    database_id="my-database",
    credentials_file="/path/to/credentials.json"
)

static convert_spanner_json(data)#

Convert Spanner JSON query results to structured graph data.

Transforms raw Spanner JSON query results into a standardized format with separate nodes and edges arrays for graph processing.

Parameters:: data (List[Any]) – Raw JSON data from Spanner query results
Returns:: Structured graph data with ‘nodes’ and ‘edges’ arrays
Return type:: List[Dict[str, Any]]

static get_edges_df(json_data)#

Convert Spanner JSON edges into a pandas DataFrame.

Extracts edge data from structured JSON results and creates a DataFrame with columns for label, identifier, source, destination, and all edge properties.

Parameters:: json_data (list) – Structured JSON data containing graph edges
Returns:: DataFrame containing edge data with properties as columns
Return type:: pd.DataFrame

static get_nodes_df(json_data)#

Convert Spanner JSON nodes into a pandas DataFrame.

Extracts node data from structured JSON results and creates a DataFrame with columns for label, identifier, and all node properties.

Parameters:: json_data (list) – Structured JSON data containing graph nodes
Returns:: DataFrame containing node data with properties as columns
Return type:: pd.DataFrame

property spanner_client: Any#

spanner_close()#

Close the active Spanner database connection.

Properly closes the underlying Spanner client connection to free resources. This should be called when you’re done using the Spanner connection.

Example

import graphistry
g = graphistry.configure_spanner(...)
# ... perform queries ...
g.spanner_close()  # Clean up connection

Return type:: None

property spanner_config: SpannerConfig#

spanner_from_client(client)#

Configure Spanner using an existing client connection.

Use this method when you already have a configured Spanner client connection and want to reuse it with Graphistry.

Parameters:: client (google.cloud.spanner_dbapi.connection.Connection) – Pre-configured Spanner database connection
Returns:: Self for method chaining
Return type:: Plottable

Example

from google.cloud import spanner
import graphistry

# Create Spanner client
spanner_client = spanner.Client(project="my-project")
instance = spanner_client.instance("my-instance")
database = instance.database("my-database")

# Use with Graphistry
g = graphistry.spanner_from_client(database)

spanner_gql(query)#

Execute GQL path query and return graph visualization.

Executes a Graph Query Language (GQL) path query on the configured Spanner database and returns a Plottable object ready for visualization. The query must return path data using SAFE_TO_JSON(p) format.

Parameters:: query (str) – GQL path query string with SAFE_TO_JSON(path) format
Returns:: Plottable object with nodes and edges populated from query results
Return type:: Plottable

Example: Basic path query

import graphistry
graphistry.configure_spanner(
    project_id="my-project",
    instance_id="my-instance", 
    database_id="my-database"
)

query = '''
GRAPH FinGraph
MATCH p = (a:Account)-[t:Transfers]->(b:Account)
LIMIT 10000
RETURN SAFE_TO_JSON(p) as path
'''

g = graphistry.spanner_gql(query)
g.plot()

spanner_gql_to_df(query)#

Execute GQL/SQL query and return results as DataFrame.

Executes a Graph Query Language (GQL) or SQL query on the configured Spanner database and returns the results as a pandas DataFrame. This method is suitable for tabular queries that don’t require graph visualization.

Parameters:: query (str) – GQL or SQL query string
Returns:: DataFrame containing query results with column names
Return type:: pd.DataFrame

Example: Aggregation query

import graphistry
graphistry.configure_spanner(
    project_id="my-project",
    instance_id="my-instance", 
    database_id="my-database"
)

query = '''
GRAPH FinGraph
MATCH (p:Person)-[:Owns]-(:Account)->(l:Loan)
RETURN p.id as PersonID, p.name AS Name, 
       SUM(l.loan_amount) AS TotalBorrowed
ORDER BY TotalBorrowed DESC
LIMIT 10
'''

df = graphistry.spanner_gql_to_df(query)
print(df.head())

Example: SQL query

query = "SELECT * FROM Account WHERE type = 'checking' LIMIT 1000"
df = graphistry.spanner_gql_to_df(query)

graphistry.plugins.spanner.init_spanner_client(cfg)#

Lazily establish a DB-API connection using the parameters in session.config.

Parameters:: cfg (SpannerConfig)
Return type:: Any

Spanner Plugin

Contents

Spanner Plugin#