mirrors/googleapis--mcp-toolbox
1
0
Fork 0
Code Issues Pull Requests Actions Deployments Models Agent Notes Packages Projects Releases Wiki Activity

chore: import upstream snapshot with attribution
CF: Deploy Dev Docs / deploy (push) Has been cancelled
Details
Sync Labels / build (push) Has been cancelled
Details
tests / unit tests (macos-latest) (push) Has been cancelled
Details
tests / unit tests (windows-latest) (push) Has been cancelled
Details
tests / unit tests (ubuntu-latest) (push) Has been cancelled
Details

Browse Source
This commit is contained in:
wehub-resource-sync
2026-07-13 13:32:45 +08:00
commit e04ed9c211
1798 changed files with 307905 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/en/integrations/spanner/_index.md
+4
View File
@@ -0,0 +1,4 @@
---
title: "Spanner"
weight: 1
---
docs/en/integrations/spanner/prebuilt-configs/_index.md
+5
View File
@@ -0,0 +1,5 @@
---
title: "Prebuilt Configs"
type: docs
description: "Prebuilt configurations for Spanner."
---
docs/en/integrations/spanner/prebuilt-configs/spanner-googlesql-dialect.md
+24
View File
@@ -0,0 +1,24 @@
---
title: "Spanner (GoogleSQL dialect)"
type: docs
description: "Details of the Spanner (GoogleSQL dialect) prebuilt configuration."
---
## Spanner (GoogleSQL dialect)
* `--prebuilt` value: `spanner`
* **Environment Variables:**
* `SPANNER_PROJECT`: The GCP project ID.
* `SPANNER_INSTANCE`: The Spanner instance ID.
* `SPANNER_DATABASE`: The Spanner database ID.
* **Permissions:**
* **Cloud Spanner Database Reader** (`roles/spanner.databaseReader`) to
execute DQL queries and list tables.
* **Cloud Spanner Database User** (`roles/spanner.databaseUser`) to
execute DML queries.
* **Tools:**
* `execute_sql`: Executes a DML SQL query.
* `execute_sql_dql`: Executes a DQL SQL query.
* `list_tables`: Lists tables in the database.
* `list_graphs`: Lists graphs in the database.
* `search_catalog`: Searches for data assets in Knowledge Catalog (Dataplex).
docs/en/integrations/spanner/prebuilt-configs/spanner-postgresql-dialect.md
+25
View File
@@ -0,0 +1,25 @@
---
title: "Spanner (PostgreSQL dialect)"
type: docs
description: "Details of the Spanner (PostgreSQL dialect) prebuilt configuration."
---
## Spanner (PostgreSQL dialect)
* `--prebuilt` value: `spanner-postgres`
* **Environment Variables:**
* `SPANNER_PROJECT`: The GCP project ID.
* `SPANNER_INSTANCE`: The Spanner instance ID.
* `SPANNER_DATABASE`: The Spanner database ID.
* **Permissions:**
* **Cloud Spanner Database Reader** (`roles/spanner.databaseReader`) to
execute DQL queries and list tables.
* **Cloud Spanner Database User** (`roles/spanner.databaseUser`) to
execute DML queries.
* **Tools:**
* `execute_sql`: Executes a DML SQL query using the PostgreSQL interface
for Spanner.
* `execute_sql_dql`: Executes a DQL SQL query using the PostgreSQL
interface for Spanner.
* `list_tables`: Lists tables in the database.
* `search_catalog`: Searches for data assets in Knowledge Catalog (Dataplex).
docs/en/integrations/spanner/source.md
+77
View File
@@ -0,0 +1,77 @@
---
title: "Spanner Source"
linkTitle: "Source"
type: docs
weight: 1
description: >
Spanner is a fully managed database service from Google Cloud that combines
relational, key-value, graph, and search capabilities.
no_list: true
---
## About
[Spanner][spanner-docs] is a fully managed, mission-critical database service
that brings together relational, graph, key-value, and search. It offers
transactional consistency at global scale, automatic, synchronous replication
for high availability, and support for two SQL dialects: GoogleSQL (ANSI 2011
with extensions) and PostgreSQL.
If you are new to Spanner, you can try to [create and query a database using
the Google Cloud console][spanner-quickstart].
[spanner-docs]: https://cloud.google.com/spanner/docs
[spanner-quickstart]:
https://cloud.google.com/spanner/docs/create-query-database-console
## Available Tools
{{< list-tools >}}
### Pre-built Configurations
- [Spanner using MCP](../../documentation/connect-to/ides/spanner_mcp.md)
Connect your IDE to Spanner using Toolbox.
## Requirements
### IAM Permissions
Spanner uses [Identity and Access Management (IAM)][iam-overview] to control
user and group access to Spanner resources at the project, Spanner instance, and
Spanner database levels. Toolbox will use your [Application Default Credentials
(ADC)][adc] to authorize and authenticate when interacting with Spanner.
In addition to [setting the ADC for your server][set-adc], you need to ensure
the IAM identity has been given the correct IAM permissions for the query
provided. See [Apply IAM roles][grant-permissions] for more information on
applying IAM permissions and roles to an identity.
[iam-overview]: https://cloud.google.com/spanner/docs/iam
[adc]: https://cloud.google.com/docs/authentication#adc
[set-adc]: https://cloud.google.com/docs/authentication/provide-credentials-adc
[grant-permissions]: https://cloud.google.com/spanner/docs/grant-permissions
## Example
```yaml
kind: source
name: my-spanner-source
type: "spanner"
project: "my-project-id"
instance: "my-instance"
database: "my_db"
# dialect: "googlesql"
```
## Reference
| **field** | **type** | **required** | **description** |
|-----------|:--------:|:------------:|---------------------------------------------------------------------------------------------------------------------|
| type | string | true | Must be "spanner". |
| project | string | true | Id of the GCP project that the cluster was created in (e.g. "my-project-id"). |
| instance | string | true | Name of the Spanner instance. |
| database | string | true | Name of the database on the Spanner instance |
| dialect | string | false | Name of the dialect type of the Spanner database, must be either `googlesql` or `postgresql`. Default: `googlesql`. |
docs/en/integrations/spanner/tools/_index.md
+4
View File
@@ -0,0 +1,4 @@
---
title: "Tools"
weight: 2
---
docs/en/integrations/spanner/tools/spanner-execute-sql.md
+42
View File
@@ -0,0 +1,42 @@
---
title: "spanner-execute-sql"
type: docs
weight: 1
description: >
A "spanner-execute-sql" tool executes a SQL statement against a Spanner
database.
---
## About
A `spanner-execute-sql` tool executes a SQL statement against a Spanner
database.
`spanner-execute-sql` takes one input parameter `sql` and run the sql
statement against the `source`.
> **Note:** This tool is intended for developer assistant workflows with
> human-in-the-loop and shouldn't be used for production agents.
## Compatible Sources
{{< compatible-sources >}}
## Example
```yaml
kind: tool
name: execute_sql_tool
type: spanner-execute-sql
source: my-spanner-instance
description: Use this tool to execute sql statement.
```
## Reference
| **field** | **type** | **required** | **description** |
|-------------|:--------:|:------------:|------------------------------------------------------------------------------------------|
| type | string | true | Must be "spanner-execute-sql". |
| source | string | true | Name of the source the SQL should execute on. |
| description | string | true | Description of the tool that is passed to the LLM. |
| readOnly | bool | false | When set to `true`, the `statement` is run as a read-only transaction. Default: `false`. |
docs/en/integrations/spanner/tools/spanner-list-graphs.md
+281
View File
@@ -0,0 +1,281 @@
---
title: "spanner-list-graphs"
type: docs
weight: 3
description: >
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.
### 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
### 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
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 >}}
## Compatible Sources
{{< compatible-sources >}}
## 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 |
## Example
### Basic Usage - List All Graphs
```yaml
kind: source
name: my-spanner-db
type: spanner
project: ${SPANNER_PROJECT}
instance: ${SPANNER_INSTANCE}
database: ${SPANNER_DATABASE}
dialect: googlesql # wont work for postgresql
---
kind: tool
name: list_all_graphs
type: spanner-list-graphs
source: my-spanner-db
description: Lists all graphs with their complete schema information
```
### List Specific Graphs
```yaml
kind: tool
name: list_specific_graphs
type: spanner-list-graphs
source: my-spanner-db
description: |
Lists schema information for specific graphs.
Example usage:
{
"graph_names": "FinGraph,SocialGraph",
"output_format": "detailed"
}
```
## Output Format
### Simple Format
When `output_format` is set to "simple", the tool returns a minimal JSON structure:
```json
[
{
"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:
```json
[
{
"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": ""
}
]
```
## Reference
| **field** | **type** | **required** | **description** |
|--------------|:--------:|:------------:|-----------------------------------------------------------------|
| type | 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 |
## Advanced Usage
### Example with Agent Integration
```yaml
kind: source
name: spanner-db
type: spanner
project: my-project
instance: my-instance
database: my-database
dialect: googlesql
---
kind: tool
name: schema_inspector
type: 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"}
```
## Troubleshooting
- 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
docs/en/integrations/spanner/tools/spanner-list-tables.md
+225
View File
@@ -0,0 +1,225 @@
---
title: "spanner-list-tables"
type: docs
weight: 3
description: >
A "spanner-list-tables" tool retrieves schema information about tables in a
Google Cloud Spanner database.
---
## About
A `spanner-list-tables` tool retrieves comprehensive schema information about
tables in a Cloud Spanner database. It automatically adapts to the database
dialect (GoogleSQL or PostgreSQL) and returns detailed metadata including
columns, constraints, and indexes.
This tool is read-only and executes pre-defined SQL queries against the
`INFORMATION_SCHEMA` tables to gather metadata. The tool automatically detects
the database dialect from the source configuration and uses the appropriate SQL
syntax.
### Features
- **Automatic Dialect Detection**: Adapts queries based on whether the database
uses GoogleSQL or PostgreSQL dialect
- **Comprehensive Schema Information**: Returns columns, data types, constraints,
indexes, and table relationships
- **Flexible Filtering**: Can list all tables or filter by specific table names
- **Output Format Options**: Choose between simple (table names only) or detailed
(full schema information) output
### Use Cases
1. **Database Documentation**: Generate comprehensive documentation of your
database schema
2. **Schema Validation**: Verify that expected tables and columns 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
## Compatible Sources
{{< compatible-sources >}}
## Parameters
The tool accepts two optional parameters:
| **parameter** | **type** | **default** | **description** |
|---------------|:--------:|:-----------:|------------------------------------------------------------------------------------------------------|
| table_names | string | "" | Comma-separated list of table names to filter. If empty, lists all tables in user-accessible schemas |
| output_format | string | "detailed" | Output format: "simple" returns only table names, "detailed" returns full schema information |
## Example
### Basic Usage - List All Tables
```yaml
kind: source
name: my-spanner-db
type: spanner
project: ${SPANNER_PROJECT}
instance: ${SPANNER_INSTANCE}
database: ${SPANNER_DATABASE}
dialect: googlesql # or postgresql
---
kind: tool
name: list_all_tables
type: spanner-list-tables
source: my-spanner-db
description: Lists all tables with their complete schema information
```
### List Specific Tables
```yaml
kind: tool
name: list_specific_tables
type: spanner-list-tables
source: my-spanner-db
description: |
Lists schema information for specific tables.
Example usage:
{
"table_names": "users,orders,products",
"output_format": "detailed"
}
```
## Output Format
### Simple Format
When `output_format` is set to "simple", the tool returns a minimal JSON structure:
```json
[
{
"schema_name": "public",
"object_name": "users",
"object_details": {
"name": "users"
}
},
{
"schema_name": "public",
"object_name": "orders",
"object_details": {
"name": "orders"
}
}
]
```
### Detailed Format
When `output_format` is set to "detailed" (default), the tool returns
comprehensive schema information:
```json
[
{
"schema_name": "public",
"object_name": "users",
"object_details": {
"schema_name": "public",
"object_name": "users",
"object_type": "BASE TABLE",
"columns": [
{
"column_name": "id",
"data_type": "INT64",
"ordinal_position": 1,
"is_not_nullable": true,
"column_default": null
},
{
"column_name": "email",
"data_type": "STRING(255)",
"ordinal_position": 2,
"is_not_nullable": true,
"column_default": null
}
],
"constraints": [
{
"constraint_name": "PK_users",
"constraint_type": "PRIMARY KEY",
"constraint_definition": "PRIMARY KEY (id)",
"constraint_columns": [
"id"
],
"foreign_key_referenced_table": null,
"foreign_key_referenced_columns": []
}
],
"indexes": [
{
"index_name": "idx_users_email",
"index_type": "INDEX",
"is_unique": true,
"is_null_filtered": false,
"interleaved_in_table": null,
"index_key_columns": [
{
"column_name": "email",
"ordering": "ASC"
}
],
"storing_columns": []
}
]
}
}
]
```
## Reference
| **field** | **type** | **required** | **description** |
|--------------|:--------:|:------------:|----------------------------------------------------|
| type | string | true | Must be "spanner-list-tables" |
| source | string | true | Name of the Spanner source to query |
| 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 |
## Advanced Usage
### Example with Agent Integration
```yaml
kind: source
name: spanner-db
type: spanner
project: my-project
instance: my-instance
database: my-database
dialect: googlesql
---
kind: tool
name: schema_inspector
type: spanner-list-tables
source: spanner-db
description: |
Use this tool to inspect database schema information.
You can:
- List all tables by leaving table_names empty
- Get specific table schemas by providing comma-separated table names
- Choose between simple (names only) or detailed (full schema) output
Examples:
1. List all tables with details: {"output_format": "detailed"}
2. Get specific tables: {"table_names": "users,orders", "output_format": "detailed"}
3. Just get table names: {"output_format": "simple"}
```
## Additional Resources
- This tool is read-only and does not modify any data
- The tool automatically handles both GoogleSQL and PostgreSQL dialects
- Large databases with many tables may take longer to query
docs/en/integrations/spanner/tools/spanner-search-catalog.md
+65
View File
@@ -0,0 +1,65 @@
---
title: "spanner-search-catalog"
type: docs
weight: 1
description: >
A "spanner-search-catalog" tool allows to search for entries based on the provided query.
---
## About
A `spanner-search-catalog` tool returns all entries in Knowledge Catalog (e.g.
tables, views, databases) with system=Spanner that matches given user query.
`spanner-search-catalog` takes a required `prompt` parameter based on which
entries are filtered and returned to the user. It also optionally accepts
following parameters:
- `databaseIds` - The IDs of the spanner database.
- `projectIds` - The IDs of the GCP project.
- `types` - The type of the data. Accepted values are: DATABASE, TABLE, VIEW.
- `pageSize` - Number of results in the search page. Defaults to `5`.
## Compatible Sources
{{< compatible-sources >}}
## Requirements
### IAM Permissions
Spanner uses [Identity and Access Management (IAM)][iam-overview] to control
user and group access to Knowledge Catalog (formerly known as Dataplex) resources. Toolbox will use your
[Application Default Credentials (ADC)][adc] to authorize and authenticate when
interacting with [Knowledge Catalog][dataplex-docs].
In addition to [setting the ADC for your server][set-adc], you need to ensure
the IAM identity has been given the correct IAM permissions for the tasks you
intend to perform. See [Knowledge Catalog IAM permissions][iam-permissions]
and [Knowledge Catalog IAM roles][iam-roles] for more information on
applying IAM permissions and roles to an identity.
[iam-overview]: https://cloud.google.com/dataplex/docs/iam-and-access-control
[adc]: https://cloud.google.com/docs/authentication#adc
[set-adc]: https://cloud.google.com/docs/authentication/provide-credentials-adc
[iam-permissions]: https://cloud.google.com/dataplex/docs/iam-permissions
[iam-roles]: https://cloud.google.com/dataplex/docs/iam-roles
[dataplex-docs]: https://cloud.google.com/dataplex/docs
## Example
```yaml
kind: tool
name: search_catalog
type: spanner-search-catalog
source: spanner-source
description: Searches for data assets (eg. Spanner tables, views, or databases) in Knowledge Catalog (formerly known as Dataplex) based on the provided search query
```
## Reference
| **field** | **type** | **required** | **description** |
|-------------|:------------------------------------------:|:------------:|--------------------------------------------------------------------------------------------------|
| type | string | true | Must be "spanner-search-catalog". |
| source | string | true | Name of the source the tool should execute on. |
| description | string | true | Description of the tool that is passed to the LLM. |
docs/en/integrations/spanner/tools/spanner-sql.md
+237
View File
@@ -0,0 +1,237 @@
---
title: "spanner-sql"
type: docs
weight: 1
description: >
A "spanner-sql" tool executes a pre-defined SQL statement against a Google
Cloud Spanner database.
---
## About
A `spanner-sql` tool executes a pre-defined SQL statement (either `googlesql` or
`postgresql`) against a Cloud Spanner database.
## Compatible Sources
{{< compatible-sources >}}
### GoogleSQL
For the `googlesql` dialect, the specified SQL statement is executed as a [data
manipulation language (DML)][gsql-dml] statements, and specified parameters will
inserted according to their name: e.g. `@name`.
> **Note:** This tool uses parameterized queries to prevent SQL injections.
> Query parameters can be used as substitutes for arbitrary expressions.
> Parameters cannot be used as substitutes for identifiers, column names, table
> names, or other parts of the query.
[gsql-dml]:
https://cloud.google.com/spanner/docs/reference/standard-sql/dml-syntax
### PostgreSQL
For the `postgresql` dialect, the specified SQL statement is executed as a [prepared
statement][pg-prepare], and specified parameters will be inserted according to
their position: e.g. `$1` will be the first parameter specified, `$2` will be
the second parameter, and so on.
[pg-prepare]: https://www.postgresql.org/docs/current/sql-prepare.html
## Example
> **Note:** This tool uses parameterized queries to prevent SQL injections.
> Query parameters can be used as substitutes for arbitrary expressions.
> Parameters cannot be used as substitutes for identifiers, column names, table
> names, or other parts of the query.
{{< tabpane persist="header" >}}
{{< tab header="GoogleSQL" lang="yaml" >}}
kind: tool
name: search_flights_by_number
type: spanner-sql
source: my-spanner-instance
statement: |
SELECT * FROM flights
WHERE airline = @airline
AND flight_number = @flight_number
LIMIT 10
description: |
Use this tool to get information for a specific flight.
Takes an airline code and flight number and returns info on the flight.
Do NOT use this tool with a flight id. Do NOT guess an airline code or flight number.
A airline code is a code for an airline service consisting of two-character
airline designator and followed by flight number, which is 1 to 4 digit number.
For example, if given CY 0123, the airline is "CY", and flight_number is "123".
Another example for this is DL 1234, the airline is "DL", and flight_number is "1234".
If the tool returns more than one option choose the date closes to today.
Example:
{{
"airline": "CY",
"flight_number": "888",
}}
Example:
{{
"airline": "DL",
"flight_number": "1234",
}}
parameters:
- name: airline
type: string
description: Airline unique 2 letter identifier
- name: flight_number
type: string
description: 1 to 4 digit number
{{< /tab >}}
{{< tab header="PostgreSQL" lang="yaml" >}}
kind: tool
name: search_flights_by_number
type: spanner
source: my-spanner-instance
statement: |
SELECT * FROM flights
WHERE airline = $1
AND flight_number = $2
LIMIT 10
description: |
Use this tool to get information for a specific flight.
Takes an airline code and flight number and returns info on the flight.
Do NOT use this tool with a flight id. Do NOT guess an airline code or flight number.
A airline code is a code for an airline service consisting of two-character
airline designator and followed by flight number, which is 1 to 4 digit number.
For example, if given CY 0123, the airline is "CY", and flight_number is "123".
Another example for this is DL 1234, the airline is "DL", and flight_number is "1234".
If the tool returns more than one option choose the date closes to today.
Example:
{{
"airline": "CY",
"flight_number": "888",
}}
Example:
{{
"airline": "DL",
"flight_number": "1234",
}}
parameters:
- name: airline
type: string
description: Airline unique 2 letter identifier
- name: flight_number
type: string
description: 1 to 4 digit number
{{< /tab >}}
{{< /tabpane >}}
### Example with Vector Search
Spanner supports high-performance vector similarity search. When using an `embeddingModel` with a `spanner-sql` tool, the tool automatically converts text parameters into the native ARRAY<FLOAT64> format required by Spanner.
#### Define the Embedding Model
See [EmbeddingModels](../../../documentation/configuration/embedding-models/_index.md) for more information.
```yaml
kind: embeddingModel
name: gemini-model
type: gemini
model: gemini-embedding-001
apiKey: ${GOOGLE_API_KEY}
dimension: 768
```
#### Vector Ingestion Tool
This tool stores both the raw text and its vector representation. It uses `valueFromParam` to hide the vector conversion logic from the LLM, ensuring the Agent only has to provide the content once.
```yaml
kind: tool
name: insert_doc_spanner
type: spanner-sql
source: my-spanner-source
statement: |
INSERT INTO vector_table (id, content, embedding)
VALUES (1, @content, @text_to_embed)
description: |
Index new documents for semantic search in Spanner.
parameters:
- name: content
type: string
description: The text content to store.
- name: text_to_embed
type: string
# Automatically copies 'content' and converts it to a FLOAT64 array
valueFromParam: content
embeddedBy: gemini-model
```
#### Vector Search Tool
This tool allows the Agent to perform a natural language search. The query string provided by the Agent is converted into a vector before the SQL is executed.
```yaml
kind: tool
name: search_docs_spanner
type: spanner-sql
source: my-spanner-source
statement: |
SELECT
id,
content,
COSINE_DISTANCE(embedding, @query) AS distance
FROM
vector_table
ORDER BY
distance
LIMIT 1
description: |
Search for documents in Spanner using natural language.
Returns the most semantically similar result.
parameters:
- name: query
type: string
description: The search query to be converted to a vector.
embeddedBy: gemini-model
```
### Example with Template Parameters
> **Note:** This tool allows direct modifications to the SQL statement,
> including identifiers, column names, and table names. **This makes it more
> vulnerable to SQL injections**. Using basic parameters only (see above) is
> recommended for performance and safety reasons. For more details, please check
> [templateParameters](../../../documentation/configuration/tools/_index.md#template-parameters).
```yaml
kind: tool
name: list_table
type: spanner
source: my-spanner-instance
statement: |
SELECT * FROM {{.tableName}};
description: |
Use this tool to list all information from a specific table.
Example:
{{
"tableName": "flights",
}}
templateParameters:
- name: tableName
type: string
description: Table to select from
```
## Reference
| **field** | **type** | **required** | **description** |
|--------------------|:--------------------------------------------:|:------------:|----------------------------------------------------------------------------------------------------------------------------------------|
| type | string | true | Must be "spanner-sql". |
| source | string | true | Name of the source the SQL should execute on. |
| description | string | true | Description of the tool that is passed to the LLM. |
| statement | string | true | SQL statement to execute on. |
| parameters | [parameters](../../../documentation/configuration/tools/_index.md#specifying-parameters) | false | List of [parameters](../../../documentation/configuration/tools/_index.md#specifying-parameters) that will be inserted into the SQL statement. |
| readOnly | bool | false | When set to `true`, the `statement` is run as a read-only transaction. Default: `false`. |
| templateParameters | [templateParameters](../../../documentation/configuration/tools/_index.md#template-parameters) | false | List of [templateParameters](../../../documentation/configuration/tools/_index.md#template-parameters) that will be inserted into the SQL statement before executing prepared statement. |