genai-toolbox/docs/en/resources/tools/spanner/spanner-list-graphs.md

title, type, weight, description

title	type	weight	description
spanner-list-graphs	docs	3	A "spanner-list-graphs" tool retrieves schema information about graphs in a Google Cloud Spanner database.

About

A spanner-list-graphs tool retrieves comprehensive schema information about graphs in a Cloud Spanner database. It returns detailed metadata including node tables, edge tables, labels and property declarations. It's compatible with:

• spanner

This tool is read-only and executes pre-defined SQL queries against the INFORMATION_SCHEMA tables to gather metadata. {{< notice warning >}} The tool only works for the GoogleSQL source dialect, as Spanner Graph isn't available in the PostgreSQL dialect. {{< /notice >}}

Features

• Comprehensive Schema Information: Returns node tables, edge tables, labels and property declarations
• Flexible Filtering: Can list all graphs or filter by specific graph names
• Output Format Options: Choose between simple (graph names only) or detailed (full schema information) output

Example

Basic Usage - List All Graphs

sources:
  my-spanner-db:
    kind: spanner
    project: ${SPANNER_PROJECT}
    instance: ${SPANNER_INSTANCE}
    database: ${SPANNER_DATABASE}
    dialect: googlesql  # wont work for postgresql

tools:
  list_all_graphs:
    kind: spanner-list-graphs
    source: my-spanner-db
    description: Lists all graphs with their complete schema information

List Specific Graphs

tools:
  list_specific_graphs:
    kind: spanner-list-graphs
    source: my-spanner-db
    description: |
      Lists schema information for specific graphs.
      Example usage:
      {
        "graph_names": "FinGraph,SocialGraph",
        "output_format": "detailed"
      }

Parameters

The tool accepts two optional parameters:

parameter	type	default	description
graph_names	string	""	Comma-separated list of graph names to filter. If empty, lists all graphs in user-accessible schemas
output_format	string	"detailed"	Output format: "simple" returns only graph names, "detailed" returns full schema information

Output Format

Simple Format

When output_format is set to "simple", the tool returns a minimal JSON structure:

[
  {
    "object_details": {
      "name": "FinGraph"
    },
    "object_name": "FinGraph",
    "schema_name": ""
  },
  {
    "object_details": {
      "name": "SocialGraph"
    },
    "object_name": "SocialGraph",
    "schema_name": ""
  }
]

Detailed Format

When output_format is set to "detailed" (default), the tool returns comprehensive schema information:

[
  {
    "object_details": {
      "catalog": "",
      "edge_tables": [
        {
          "baseCatalogName": "",
          "baseSchemaName": "",
          "baseTableName": "Knows",
          "destinationNodeTable": {
            "edgeTableColumns": [
              "DstId"
            ],
            "nodeTableColumns": [
              "Id"
            ],
            "nodeTableName": "Person"
          },
          "keyColumns": [
            "SrcId",
            "DstId"
          ],
          "kind": "EDGE",
          "labelNames": [
            "Knows"
          ],
          "name": "Knows",
          "propertyDefinitions": [
            {
              "propertyDeclarationName": "DstId",
              "valueExpressionSql": "DstId"
            },
            {
              "propertyDeclarationName": "SrcId",
              "valueExpressionSql": "SrcId"
            }
          ],
          "sourceNodeTable": {
            "edgeTableColumns": [
              "SrcId"
            ],
            "nodeTableColumns": [
              "Id"
            ],
            "nodeTableName": "Person"
          }
        }
      ],
      "labels": [
        {
          "name": "Knows",
          "propertyDeclarationNames": [
            "DstId",
            "SrcId"
          ]
        },
        {
          "name": "Person",
          "propertyDeclarationNames": [
            "Id",
            "Name"
          ]
        }
      ],
      "node_tables": [
        {
          "baseCatalogName": "",
          "baseSchemaName": "",
          "baseTableName": "Person",
          "keyColumns": [
            "Id"
          ],
          "kind": "NODE",
          "labelNames": [
            "Person"
          ],
          "name": "Person",
          "propertyDefinitions": [
            {
              "propertyDeclarationName": "Id",
              "valueExpressionSql": "Id"
            },
            {
              "propertyDeclarationName": "Name",
              "valueExpressionSql": "Name"
            }
          ]
        }
      ],
      "object_name": "SocialGraph",
      "property_declarations": [
        {
          "name": "DstId",
          "type": "INT64"
        },
        {
          "name": "Id",
          "type": "INT64"
        },
        {
          "name": "Name",
          "type": "STRING"
        },
        {
          "name": "SrcId",
          "type": "INT64"
        }
      ],
      "schema_name": ""
    },
    "object_name": "SocialGraph",
    "schema_name": ""
  }
]

Use Cases

1. Database Documentation: Generate comprehensive documentation of your database schema
2. Schema Validation: Verify that expected graphs, node and edge exist
3. Migration Planning: Understand the current schema before making changes
4. Development Tools: Build tools that need to understand database structure
5. Audit and Compliance: Track schema changes and ensure compliance with data governance policies

Example with Agent Integration

sources:
  spanner-db:
    kind: spanner
    project: my-project
    instance: my-instance
    database: my-database
    dialect: googlesql

tools:
  schema_inspector:
    kind: spanner-list-graphs
    source: spanner-db
    description: |
      Use this tool to inspect database schema information.
      You can:
      - List all graphs by leaving graph_names empty
      - Get specific graph schemas by providing comma-separated graph names
      - Choose between simple (names only) or detailed (full schema) output
      
      Examples:
      1. List all graphs with details: {"output_format": "detailed"}
      2. Get specific graphs: {"graph_names": "FinGraph,SocialGraph", "output_format": "detailed"}
      3. Just get graph names: {"output_format": "simple"}

Reference

field	type	required	description
kind	string	true	Must be "spanner-list-graphs"
source	string	true	Name of the Spanner source to query (dialect must be GoogleSQL)
description	string	false	Description of the tool that is passed to the LLM
authRequired	string[]	false	List of auth services required to invoke this tool

Notes

• This tool is read-only and does not modify any data
• The tool only works for the GoogleSQL source dialect
• Large databases with many graphs may take longer to query