mirror of
https://github.com/googleapis/genai-toolbox.git
synced 2026-02-11 23:55:07 -05:00
docs(spanner): add docs (#128)
This commit is contained in:
Yuan
@@ -29,3 +29,4 @@ We currently support the following types of kinds of sources:
|
||||
* [cloud-sql-postgres](./cloud-sql-pg.md) - Connect to a Cloud SQL for
|
||||
PostgreSQL instance.
|
||||
* [postgres](./postgres.md) - Connect to any PostgreSQL compatible database.
|
||||
* [spanner](./spanner.md) - Connect to a Spanner database.
|
||||
|
||||
49
docs/sources/spanner.md
Normal file
49
docs/sources/spanner.md
Normal file
@@ -0,0 +1,49 @@
|
||||
# Spanner Source
|
||||
|
||||
[Spanner][spanner-docs] 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
|
||||
|
||||
## Requirements
|
||||
|
||||
### IAM Identity
|
||||
By default, Spanner uses the [OAuth 2.0][oauth2] for API authentication and
|
||||
authorization. The Cloud Spanner API uses your [Application Default Credentials
|
||||
(ADC)][adc] to authorize your connection to Spanner.
|
||||
|
||||
In addition to [setting the ADC for your server][set-adc], you need to ensure the IAM identity has been given the following IAM permissions:
|
||||
- `roles/spanner.databaseUser`
|
||||
|
||||
[oauth2]: https://datatracker.ietf.org/doc/html/rfc6749
|
||||
[adc]: https://cloud.google.com/docs/authentication#adc
|
||||
[set-adc]: https://cloud.google.com/docs/authentication/provide-credentials-adc
|
||||
|
||||
## Example
|
||||
|
||||
```yaml
|
||||
sources:
|
||||
my-spanner-source:
|
||||
kind: "spanner"
|
||||
project: "my-project-name"
|
||||
instance: "my-instance"
|
||||
database: "my_db"
|
||||
# dialect: "googlesql"
|
||||
```
|
||||
|
||||
## Reference
|
||||
|
||||
| **field** | **type** | **required** | **description** |
|
||||
|-----------|:--------:|:------------:|------------------------------------------------------------------------------|
|
||||
| kind | string | true | Must be "spanner". |
|
||||
| project | string | true | Name of the GCP project that the cluster was created in (e.g. "my-project"). |
|
||||
| instance | string | true | Name of the AlloyDB instance within the cluser (e.g. "my-instance"). |
|
||||
| database | string | true | Name of the Postgres database to connect to (e.g. "my_db"). |
|
||||
| dialect | string | true | Name of the dialect type of the Spanner database, must be either `googlesql` or `postgresql`. Default: `googlesql`. |
|
||||
@@ -48,6 +48,8 @@ We currently support the following types of kinds of tools:
|
||||
|
||||
* [postgres-sql](./postgres-sql.md) - Run a PostgreSQL statement against a
|
||||
PostgreSQL-compatible database.
|
||||
* [spanner](./spanner.md) - Run a Spanner (either googlesql or postgresql)
|
||||
statement againts Spanner database.
|
||||
|
||||
|
||||
## Specifying Parameters
|
||||
|
||||
110
docs/tools/spanner.md
Normal file
110
docs/tools/spanner.md
Normal file
@@ -0,0 +1,110 @@
|
||||
# Spanner Tool
|
||||
|
||||
A "spanner-sql" tool executes a pre-defined SQL statement (either
|
||||
`googlesql` or `postgresql`) against Spanner database. It's
|
||||
compatible with any of the following sources:
|
||||
- [spanner](../sources/spanner.md)
|
||||
|
||||
For `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".
|
||||
|
||||
For `postgresql` dialect, the specified SQL statement is executed as a
|
||||
[prepared statement][pg-prepare], and specified parameters will inserted according
|
||||
to their position: e.g. "$1" will be the first parameter specified, "$@" will be the
|
||||
second parameter, and so on.
|
||||
|
||||
|
||||
[gsql-dml]: https://cloud.google.com/spanner/docs/reference/standard-sql/dml-syntax
|
||||
[pg-prepare]: https://www.postgresql.org/docs/current/sql-prepare.html
|
||||
|
||||
## Example
|
||||
|
||||
For `googlesql` dialect:
|
||||
```yaml
|
||||
tools:
|
||||
search_flights_by_number:
|
||||
kind: spanner
|
||||
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
|
||||
```
|
||||
|
||||
For `postgresql` dialect:
|
||||
```yaml
|
||||
tools:
|
||||
search_flights_by_number:
|
||||
kind: 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
|
||||
```
|
||||
|
||||
## Reference
|
||||
|
||||
| **field** | **type** | **required** | **description** |
|
||||
|-------------|:--------------------------------------------:|:------------:|-----------------------------------------------------------------------------------------------------|
|
||||
| kind | string | true | Must be "postgres-generic". |
|
||||
| source | string | true | Name of the source the SQL should execute on. |
|
||||
| description | string | true | Port to connect to (e.g. "5432") |
|
||||
| statement | string | true | SQL statement to execute on. |
|
||||
| parameters | [parameter](README.md#specifying-parameters) | true | List of [parameters](README.md#specifying-parameters) that will be inserted into the SQL statement. |
|
||||
|
||||
Reference in New Issue
Block a user