Skip to content

Commit a0f44d3

Browse files
gRedHeadphoneaverikitsch
gRedHeadphone
and
averikitsch
authored
feat(tools/spanner-list-graph): tool impl + docs + tests (googleapis#1923)
## Description Spanner List Graphs tool, similar to list tables it can be used to get all/specific graph details ## PR Checklist - [x] Make sure you reviewed [CONTRIBUTING.md](https://github.com/googleapis/genai-toolbox/blob/main/CONTRIBUTING.md) - [x] Make sure to open an issue as a [bug/issue](https://github.com/googleapis/genai-toolbox/issues/new/choose) before writing your code! That way we can discuss the change, evaluate designs, and agree on the general idea - [x] Ensure the tests and linter pass - [x] Code coverage does not decrease (if any source code was changed) - [x] Appropriate docs were updated (if necessary) - [x] Make sure to add `!` if this involve a breaking change 🛠️ Fixes googleapis#1916 --------- Co-authored-by: Averi Kitsch <akitsch@google.com>
1 parent 8783383 commit a0f44d3

File tree

6 files changed

+842
-2
lines changed

6 files changed

+842
-2
lines changed

‎cmd/root.go‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -200,6 +200,7 @@ import (
200200
_ "github.com/googleapis/genai-toolbox/internal/tools/singlestore/singlestoreexecutesql"
201201
_ "github.com/googleapis/genai-toolbox/internal/tools/singlestore/singlestoresql"
202202
_ "github.com/googleapis/genai-toolbox/internal/tools/spanner/spannerexecutesql"
203+
_ "github.com/googleapis/genai-toolbox/internal/tools/spanner/spannerlistgraphs"
203204
_ "github.com/googleapis/genai-toolbox/internal/tools/spanner/spannerlisttables"
204205
_ "github.com/googleapis/genai-toolbox/internal/tools/spanner/spannersql"
205206
_ "github.com/googleapis/genai-toolbox/internal/tools/sqlite/sqliteexecutesql"

‎docs/en/resources/sources/spanner.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,9 @@ the Google Cloud console][spanner-quickstart].
3434
- [`spanner-list-tables`](../tools/spanner/spanner-list-tables.md)
3535
Retrieve schema information about tables in a Spanner database.
3636

37+
- [`spanner-list-graphs`](../tools/spanner/spanner-list-graphs.md)
38+
Retrieve schema information about graphs in a Spanner database.
39+
3740
### Pre-built Configurations
3841

3942
- [Spanner using MCP](https://googleapis.github.io/genai-toolbox/how-to/connect-ide/spanner_mcp/)

‎docs/en/resources/tools/spanner/spanner-list-graphs.md‎

Lines changed: 276 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,276 @@
1+
---
2+
title: "spanner-list-graphs"
3+
type: docs
4+
weight: 3
5+
description: >
6+
A "spanner-list-graphs" tool retrieves schema information about graphs in a
7+
Google Cloud Spanner database.
8+
---
9+
10+
## About
11+
12+
A `spanner-list-graphs` tool retrieves comprehensive schema information about
13+
graphs in a Cloud Spanner database. It returns detailed metadata including
14+
node tables, edge tables, labels and property declarations. It's compatible with:
15+
16+
- [spanner](../../sources/spanner.md)
17+
18+
This tool is read-only and executes pre-defined SQL queries against the
19+
`INFORMATION_SCHEMA` tables to gather metadata.
20+
{{< notice warning >}}
21+
The tool only works for the GoogleSQL
22+
source dialect, as Spanner Graph isn't available in the PostgreSQL dialect.
23+
{{< /notice >}}
24+
25+
## Features
26+
27+
- **Comprehensive Schema Information**: Returns node tables, edge tables, labels
28+
and property declarations
29+
- **Flexible Filtering**: Can list all graphs or filter by specific graph names
30+
- **Output Format Options**: Choose between simple (graph names only) or detailed
31+
(full schema information) output
32+
33+
## Example
34+
35+
### Basic Usage - List All Graphs
36+
37+
```yaml
38+
sources:
39+
my-spanner-db:
40+
kind: spanner
41+
project: ${SPANNER_PROJECT}
42+
instance: ${SPANNER_INSTANCE}
43+
database: ${SPANNER_DATABASE}
44+
dialect: googlesql # wont work for postgresql
45+
46+
tools:
47+
list_all_graphs:
48+
kind: spanner-list-graphs
49+
source: my-spanner-db
50+
description: Lists all graphs with their complete schema information
51+
```
52+
53+
### List Specific Graphs
54+
55+
```yaml
56+
tools:
57+
list_specific_graphs:
58+
kind: spanner-list-graphs
59+
source: my-spanner-db
60+
description: |
61+
Lists schema information for specific graphs.
62+
Example usage:
63+
{
64+
"graph_names": "FinGraph,SocialGraph",
65+
"output_format": "detailed"
66+
}
67+
```
68+
69+
## Parameters
70+
71+
The tool accepts two optional parameters:
72+
73+
| **parameter** | **type** | **default** | **description** |
74+
|---------------|:--------:|:-----------:|------------------------------------------------------------------------------------------------------|
75+
| graph_names | string | "" | Comma-separated list of graph names to filter. If empty, lists all graphs in user-accessible schemas |
76+
| output_format | string | "detailed" | Output format: "simple" returns only graph names, "detailed" returns full schema information |
77+
78+
## Output Format
79+
80+
### Simple Format
81+
82+
When `output_format` is set to "simple", the tool returns a minimal JSON structure:
83+
84+
```json
85+
[
86+
{
87+
"object_details": {
88+
"name": "FinGraph"
89+
},
90+
"object_name": "FinGraph",
91+
"schema_name": ""
92+
},
93+
{
94+
"object_details": {
95+
"name": "SocialGraph"
96+
},
97+
"object_name": "SocialGraph",
98+
"schema_name": ""
99+
}
100+
]
101+
```
102+
103+
### Detailed Format
104+
105+
When `output_format` is set to "detailed" (default), the tool returns
106+
comprehensive schema information:
107+
108+
```json
109+
[
110+
{
111+
"object_details": {
112+
"catalog": "",
113+
"edge_tables": [
114+
{
115+
"baseCatalogName": "",
116+
"baseSchemaName": "",
117+
"baseTableName": "Knows",
118+
"destinationNodeTable": {
119+
"edgeTableColumns": [
120+
"DstId"
121+
],
122+
"nodeTableColumns": [
123+
"Id"
124+
],
125+
"nodeTableName": "Person"
126+
},
127+
"keyColumns": [
128+
"SrcId",
129+
"DstId"
130+
],
131+
"kind": "EDGE",
132+
"labelNames": [
133+
"Knows"
134+
],
135+
"name": "Knows",
136+
"propertyDefinitions": [
137+
{
138+
"propertyDeclarationName": "DstId",
139+
"valueExpressionSql": "DstId"
140+
},
141+
{
142+
"propertyDeclarationName": "SrcId",
143+
"valueExpressionSql": "SrcId"
144+
}
145+
],
146+
"sourceNodeTable": {
147+
"edgeTableColumns": [
148+
"SrcId"
149+
],
150+
"nodeTableColumns": [
151+
"Id"
152+
],
153+
"nodeTableName": "Person"
154+
}
155+
}
156+
],
157+
"labels": [
158+
{
159+
"name": "Knows",
160+
"propertyDeclarationNames": [
161+
"DstId",
162+
"SrcId"
163+
]
164+
},
165+
{
166+
"name": "Person",
167+
"propertyDeclarationNames": [
168+
"Id",
169+
"Name"
170+
]
171+
}
172+
],
173+
"node_tables": [
174+
{
175+
"baseCatalogName": "",
176+
"baseSchemaName": "",
177+
"baseTableName": "Person",
178+
"keyColumns": [
179+
"Id"
180+
],
181+
"kind": "NODE",
182+
"labelNames": [
183+
"Person"
184+
],
185+
"name": "Person",
186+
"propertyDefinitions": [
187+
{
188+
"propertyDeclarationName": "Id",
189+
"valueExpressionSql": "Id"
190+
},
191+
{
192+
"propertyDeclarationName": "Name",
193+
"valueExpressionSql": "Name"
194+
}
195+
]
196+
}
197+
],
198+
"object_name": "SocialGraph",
199+
"property_declarations": [
200+
{
201+
"name": "DstId",
202+
"type": "INT64"
203+
},
204+
{
205+
"name": "Id",
206+
"type": "INT64"
207+
},
208+
{
209+
"name": "Name",
210+
"type": "STRING"
211+
},
212+
{
213+
"name": "SrcId",
214+
"type": "INT64"
215+
}
216+
],
217+
"schema_name": ""
218+
},
219+
"object_name": "SocialGraph",
220+
"schema_name": ""
221+
}
222+
]
223+
```
224+
225+
## Use Cases
226+
227+
1. **Database Documentation**: Generate comprehensive documentation of your
228+
database schema
229+
2. **Schema Validation**: Verify that expected graphs, node and edge exist
230+
3. **Migration Planning**: Understand the current schema before making changes
231+
4. **Development Tools**: Build tools that need to understand database structure
232+
5. **Audit and Compliance**: Track schema changes and ensure compliance with
233+
data governance policies
234+
235+
## Example with Agent Integration
236+
237+
```yaml
238+
sources:
239+
spanner-db:
240+
kind: spanner
241+
project: my-project
242+
instance: my-instance
243+
database: my-database
244+
dialect: googlesql
245+
246+
tools:
247+
schema_inspector:
248+
kind: spanner-list-graphs
249+
source: spanner-db
250+
description: |
251+
Use this tool to inspect database schema information.
252+
You can:
253+
- List all graphs by leaving graph_names empty
254+
- Get specific graph schemas by providing comma-separated graph names
255+
- Choose between simple (names only) or detailed (full schema) output
256+
257+
Examples:
258+
1. List all graphs with details: {"output_format": "detailed"}
259+
2. Get specific graphs: {"graph_names": "FinGraph,SocialGraph", "output_format": "detailed"}
260+
3. Just get graph names: {"output_format": "simple"}
261+
```
262+
263+
## Reference
264+
265+
| **field** | **type** | **required** | **description** |
266+
|--------------|:--------:|:------------:|-----------------------------------------------------------------|
267+
| kind | string | true | Must be "spanner-list-graphs" |
268+
| source | string | true | Name of the Spanner source to query (dialect must be GoogleSQL) |
269+
| description | string | false | Description of the tool that is passed to the LLM |
270+
| authRequired | string[] | false | List of auth services required to invoke this tool |
271+
272+
## Notes
273+
274+
- This tool is read-only and does not modify any data
275+
- The tool only works for the GoogleSQL source dialect
276+
- Large databases with many graphs may take longer to query

0 commit comments

Comments
 (0)