1. Descripción general
En este codelab, se demuestra cómo emitir consultas de gráficos en Spanner con gemini-cli y los servidores del Protocolo de contexto del modelo (MCP) de Google. Al integrar la base de datos multimodelos de Spanner, incluido Spanner Graph, con el servicio de MCP administrado, puedes usar el lenguaje natural para descubrir relaciones ocultas en tus datos (como círculos de fraude o dependencias de la cadena de suministro) en una sola base de datos sin escribir consultas complejas en GQL (lenguaje de consultas de gráficos) o SQL de forma manual.
Qué aprenderás
- Cómo configurar una base de datos multimodelos de Spanner, incluido Spanner Graph para MCP
- Cómo conectar la Gemini CLI a un extremo de servicio de Spanner remoto administrado
- Cómo usar el lenguaje natural para generar automáticamente SQL integrado con GQL y realizar recorridos de gráficos y coincidencias de patrones junto con operaciones relacionales
- Prácticas recomendadas para proteger los datos de gráficos en los flujos de trabajo de IA
Requisitos previos
- Un proyecto de Google Cloud con facturación habilitada
- Acceso a una terminal (como Cloud Shell) Consulta este codelab.
- La CLI de
gclouddebe estar instalada y autenticada. - Acceso a Gemini CLI
NOTA: Ejecutarás todos los comandos en una terminal de Unix. Consulta los requisitos previos anteriores para obtener acceso a una terminal con acceso a gcloud con la autenticación adecuada.
2. Configura el entorno de Spanner Multi-model
El MCP administrado funciona mejor cuando el esquema de la base de datos está predefinido. Crearemos un gráfico de "Detección de fraudes" financieros basado en las muestras de Spanner Graph.
Habilita las APIs
export PROJECT_ID="YOUR_PROJECT_ID"
gcloud config set project ${PROJECT_ID}
# Enable Spanner's MCP endpoint
gcloud beta services mcp enable spanner.googleapis.com --project=${PROJECT_ID}
Crea el esquema de la base de datos
Crea una instancia y una base de datos con tablas de bases de datos y un gráfico de propiedades. Este esquema hace un seguimiento de las Cuentas, las Personas y las Transferencias entre ellas.
NOTA: Puedes ejecutar estas instrucciones DDL desde Spanner Studio. Consulta este vínculo para obtener información sobre cómo crear y consultar una base de datos de Spanner desde la consola de GCP.
CREATE TABLE Account (
id INT64 NOT NULL,
create_time TIMESTAMP,
is_blocked BOOL,
nick_name STRING(MAX),
) PRIMARY KEY(id);
CREATE TABLE Person (
id INT64 NOT NULL,
name STRING(MAX),
birthday TIMESTAMP,
country STRING(MAX),
city STRING(MAX),
) PRIMARY KEY(id);
CREATE TABLE AccountTransferAccount (
id INT64 NOT NULL,
to_id INT64 NOT NULL,
amount FLOAT64,
create_time TIMESTAMP NOT NULL,
order_number STRING(MAX),
FOREIGN KEY(to_id) REFERENCES Account(id),
) PRIMARY KEY(id, to_id, create_time),
INTERLEAVE IN PARENT Account ON DELETE CASCADE;
CREATE TABLE PersonOwnAccount (
id INT64 NOT NULL,
account_id INT64 NOT NULL,
create_time TIMESTAMP,
FOREIGN KEY(account_id) REFERENCES Account(id),
) PRIMARY KEY(id, account_id),
INTERLEAVE IN PARENT Person ON DELETE CASCADE;
CREATE PROPERTY GRAPH FinGraph
NODE TABLES(
Account
KEY(id)
LABEL Account PROPERTIES(
create_time,
id,
is_blocked,
nick_name),
Person
KEY(id)
LABEL Person PROPERTIES(
birthday,
city,
country,
id,
name)
)
EDGE TABLES(
AccountTransferAccount
KEY(id, to_id, create_time)
SOURCE KEY(id) REFERENCES Account(id)
DESTINATION KEY(to_id) REFERENCES Account(id)
LABEL Transfers PROPERTIES(
amount,
create_time,
id,
order_number,
to_id),
PersonOwnAccount
KEY(id, account_id)
SOURCE KEY(id) REFERENCES Person(id)
DESTINATION KEY(account_id) REFERENCES Account(id)
LABEL Owns PROPERTIES(
account_id,
create_time,
id)
);
Propaga datos
Insertar personas
INSERT INTO Person (id, name, birthday, country, city) VALUES
(1, 'Alex', '1990-01-01T00:00:00Z', 'USA', 'New York'),
(2, 'Lee', '1985-05-15T00:00:00Z', 'USA', 'San Francisco'),
(3, 'Dana', '1995-08-20T00:00:00Z', 'Canada', 'Vancouver'),
(4, 'Maria', '1992-04-15T00:00:00Z', 'USA', 'Chicago'),
(5, 'David', '1988-11-20T00:00:00Z', 'Canada', 'Toronto');
Insertar cuentas
INSERT INTO Account (id, create_time, is_blocked, nick_name) VALUES
(7, '2020-01-10T14:22:20.222Z', false, 'Vacation Fund'),
(16, '2020-01-28T01:55:09.206Z', true, 'Vacation Fund'),
(20, '2020-02-18T13:44:20.655Z', false, 'Rainy Day Fund'),
(25, '2023-01-15T10:00:00Z', false, 'Savings'),
(30, '2023-02-20T11:00:00Z', false, 'Checking');
Vincula personas a cuentas
INSERT INTO PersonOwnAccount (id, account_id, create_time) VALUES
(1, 7, '2020-01-10T14:22:20.222Z'),
(2, 16, '2020-01-28T01:55:09.206Z'),
(3, 20, '2020-02-18T13:44:20.655Z'),
(4, 25, '2023-01-15T10:00:00Z'),
(5, 30, '2023-02-20T11:00:00Z');
Cómo agregar transferencias
INSERT INTO AccountTransferAccount (id, to_id, amount, create_time, order_number) VALUES
(7, 16, 300, '2024-02-28T10:00:00Z', 'ORD123'),
(7, 16, 100, '2024-02-29T11:00:00Z', 'ORD124'),
(16, 20, 300, '2024-02-29T12:00:00Z', 'ORD125'),
(20, 7, 500, '2024-02-29T13:00:00Z', 'ORD126'),
(20, 16, 200, '2024-02-29T14:00:00Z', 'ORD127'),
(7, 25, 150.75, '2024-03-01T12:00:00Z', 'ORD456'),
(25, 30, 200.00, '2024-03-02T14:30:00Z', 'ORD457'),
(30, 16, 50.25, '2024-03-03T16:00:00Z', 'ORD458');
3. Configura Gemini CLI y Spanner MCP
El lab está diseñado para usar Gemini CLI como el agente principal para realizar la mayoría de las acciones, y el primer paso es configurarlo para que funcione con el servidor de MCP de Spanner remoto. También se recomienda usar la versión más reciente de Gemini CLI y la versión más reciente de Gemini, como Gemini-3-pro o Gemini-3-flash (actualmente en versión preliminar).
Si ya tienes la versión más reciente de Gemini CLI y la configuraste para usar los modelos de Gemini más recientes, puedes omitir los próximos 2 pasos y pasar directamente al paso 3.
Obtén una clave de API de Gemini
Para usar los modelos de Gemini más recientes en tu CLI de Gemini, debes configurarla con una autenticación de clave de API. Podemos obtener la clave de API en Google AI Studio
- Ve a Google AI Studio -> Obtener clave de API en tu navegador.
- En el lado derecho de la pantalla, haz clic en el botón
Create API key. - En la ventana emergente, elige tu proyecto o impórtalo si no se ve allí.
- Crea la clave de API.
- Puedes copiar la clave con el botón de copiar que se encuentra en el lado derecho.
La clave está preparada y ahora podemos usarla para Gemini CLI.
Configura Gemini CLI
Puedes configurar Gemini CLI a través del archivo de configuración de parámetros o de forma interactiva con el comando /settings. Queremos que la configuración se conserve en el archivo de configuración.
Primero, crearemos un directorio para nuestro proyecto. Llamemos al directorio projectspannermcp y cambiemos a ese directorio con los siguientes comandos.
mkdir ~/projectspannermcp
cd ~/projectspannermcp
En el directorio, crearemos otro para los archivos de configuración de Gemini y ejecutaremos todos nuestros comandos. De forma predeterminada, Gemini CLI usa un archivo de configuración de alcance del usuario y extensiones instaladas en el directorio ~/.gemini. Sin embargo, crearemos nuestra propia configuración de alcance del proyecto en nuestro directorio ~/projectspannermcp. Comencemos por crear el directorio y los archivos de configuración.
mkdir ~/projectspannermcp/.gemini
touch ~/projectspannermcp/.gemini/settings.json
Luego, abrimos el archivo ~/projectspannermcp/.gemini/settings.json con el editor de Cloud Shell.
edit ~/projectspannermcp/.gemini/settings.json
En la ventana del editor que se abrió, agrega la siguiente configuración.
{
"general": {
"preferredEditor": "vscode",
"previewFeatures": true,
"sessionRetention": {
"enabled": true
}
},
"ide": {
"enabled": true,
"hasSeenNudge": true
},
"security": {
"auth": {
"selectedType": "gemini-api-key"
}
},
"ui": {
"theme": "Default"
},
"tools": {
"shell": {
"enableInteractiveShell": false
}
}
}
Después de editar el archivo, puedes usar ctrl+s para guardar los cambios y volver a la terminal haciendo clic en el botón Open Terminal.
El archivo settings.json anterior establece tu tipo de autenticación de Gemini CLI como gemini-api-key, y debes proporcionar la clave al modelo. Para ello, crea un archivo .env en el directorio con el que deseas trabajar con Gemini CLI y almacena tu clave de API para la autenticación de Gemini CLI como una variable de entorno que se seleccionará cuando inicies el IDE.
Editemos el archivo con el editor de Cloud Shell
edit ~/projectspannermcp/.env
Almacena la clave de API que creaste en el paso "Obtén la clave de API de Gemini" anterior.
GEMINI_API_KEY= <YOUR_API_KEY>
Ahora puedes volver a la terminal y continuar. El siguiente paso es actualizar Gemini CLI a la versión más reciente. La versión en Google Cloud Shell o en tu entorno puede estar desactualizada y es posible que no funcione correctamente con las configuraciones y los servicios de MCP más recientes. Por lo tanto, es importante que actualices Gemini CLI a la versión más reciente y la inicies. En la terminal, ejecuta lo siguiente.
cd ~/projectspannermcp/
npm install -g @google/gemini-cli@latest
Ahora puedes verificar la versión. Ten en cuenta que, si trabajas en Google Cloud Shell, cada vez que reinicies el shell, es posible que vuelva a la versión anterior. Los cambios que realices en la CLI de Gemini no son permanentes en Cloud Shell.
gemini --version
Debería mostrar la versión más reciente de Gemini CLI (versión 0.27 en el momento de escribir el lab). Puedes verificar la versión más reciente de Gemini CLI aquí. Ahora podemos iniciarlo y asegurarnos de que esté usando el modelo de Gemini más reciente. Ejecuta el siguiente comando en la carpeta de tu proyecto para iniciar Gemini CLI.
gemini
Cuando se inicie Gemini CLI, puedes verificar la versión y el modelo ejecutando el comando /about en la interfaz. Deberías obtener algo similar a la siguiente imagen.
Puedes ver que usa el modelo Gemini-3 más reciente. Los siguientes pasos que demuestran las consultas en lenguaje natural requieren el uso del modelo Gemini-3.
Configura Gemini CLI para usar el MCP de Spanner
Tenemos una cosa más que agregar al archivo settings.json. Primero, sal de la CLI de Gemini (puedes presionar Ctrl+C dos veces).
En el mismo settings.json que se mostró anteriormente, agregaremos el bit para configurar nuestro servidor de MCP de Spanner. A continuación, incluimos el archivo settings.json completo. Observa el bit que comienza con "mcpServers".
{
"general": {
"preferredEditor": "vscode",
"previewFeatures": true,
"sessionRetention": {
"enabled": true
}
},
"ide": {
"enabled": true,
"hasSeenNudge": true
},
"security": {
"auth": {
"selectedType": "gemini-api-key"
}
},
"ui": {
"theme": "Default"
},
"tools": {
"shell": {
"enableInteractiveShell": false
}
},
"mcpServers": {
"spanner": {
"httpUrl": "https://spanner.googleapis.com/mcp",
"authProviderType": "google_credentials",
"oauth": {
"scopes": ["https://www.googleapis.com/auth/spanner.admin",
"https://www.googleapis.com/auth/spanner.data"]
},
"timeout": 5000
}
},
"mcp": {
"allowed": [
"spanner"
]
}
}
Antes de continuar con el siguiente paso, autentícate.
gcloud auth application-default login
Después de la autenticación, vuelve a iniciar gemini-cli.
gemini
4. Genera modelos múltiples, incluidas las búsquedas centradas en gráficos
Comencemos por enumerar las instancias de Spanner en tu proyecto configurado.
"Enumera todas las instancias de Spanner en mi proyecto <project1> (reemplaza por tu ID del proyecto)".
Respuesta:
The Spanner instances in your project are:
[instance1]
"Enumera todas las bases de datos en <instance1> (reemplaza con tu instancia)".
Respuesta:
The Spanner databases in [instance1] are:
[database1]
A continuación, le indicaremos a Gemini que recuerde la instancia o la base de datos en la que ejecutaste las instrucciones DDL y las instrucciones de inserción en la sección de configuración de Spanner:
"Supón que todas las consultas se deben enviar a la base de datos <your-db> en la instancia <your-instance>, a menos que se indique lo contrario".
NOTE: Usa la instancia o la base de datos en la que ejecutaste las instrucciones DDL y las instrucciones de inserción anteriores.
Una vez conectado, el modelo de Gemini comprende el esquema del grafo. Ahora puedes ejecutar exploraciones sofisticadas con lenguaje natural.
El modelo traducirá automáticamente estas instrucciones a GQL (Graph Query Language):
Identifica las estructuras de red
"Describe la estructura del gráfico de propiedades "FinGraph". ¿Cuáles son las etiquetas de los nodos y las aristas?"
Respuesta:
Node Labels
* `Account`: Represents financial accounts.
* Properties: id, create_time, is_blocked, nick_name
* `Person`: Represents individuals.
* Properties: id, name, birthday, country, city
Edge Labels
* `Transfers`: Represents a transfer between two Account nodes.
* Source: Account
* Destination: Account
* Properties: id, to_id, amount, create_time, order_number
* `Owns`: Represents a Person owning an Account.
* Source: Person
* Destination: Account
* Properties: id, account_id, create_time
Detección de fraudes y ciclos
"Encuentra cualquier transferencia circular en la que se haya enviado dinero de la cuenta A y, finalmente, se haya devuelto a la cuenta A en un máximo de 3 saltos".
Respuesta:
The analysis confirms the following circular transfers where money returns to the originating account within 3 hops:
3-Hop Cycles
Money travels through two intermediate accounts before returning to the origin.
* Account 16 (Involved in multiple 3-hop paths)
* Account 20 (Involved in multiple 3-hop paths)
* Account 7 (Involved in multiple 3-hop paths)
These accounts are participating in circular flow patterns of varying lengths.
Análisis de relaciones profundas
"Identifica a todas las personas que son propietarias de cuentas que enviaron más de USD 499 a cuentas que pertenecen a otras personas en los últimos 24 meses".
Respuesta:
Dana is the only person who owns an account that has sent more than $499 to an account owned by a different person in the last 24 months.
(Specifically, her account sent exactly $500, which is the maximum transfer amount in the database).
Búsqueda de rutas
"Encuentra la ruta más corta de transferencias entre el ID de cuenta 16 y el ID de cuenta 20".
Respuesta:
The shortest path between Account 16 and Account 20 is 1 hop.
This means there is a direct transfer from Account 16 to Account 20.
5. ¡Felicitaciones!
Felicitaciones por completar el codelab.
Temas abordados
En este codelab, aprendiste a configurar gemini-cli con el servidor de MCP de Spanner y a emitir consultas en lenguaje natural en tus datos de Spanner Graph para obtener estadísticas. A continuación, se incluye un resumen de los eventos clave:
- Infraestructura administrada: Se habilitó el servidor de MCP de Spanner remoto, lo que eliminó la necesidad de proxies locales o de la MCP Toolbox.
- Integración de gráficos: Se configuró un gráfico de propiedades de Spanner (FinGraph) con nodos y aristas para representar relaciones complejas.
- Herramientas nativas: Se conectó Gemini CLI directamente al extremo administrado de Spanner con un esquema de URI estándar.
- SQL y GQL en lenguaje natural: Se ejercitó el servidor con instrucciones específicas del gráfico, lo que permitió que el LLM realizara recorridos de múltiples saltos y detección de ciclos sin codificación manual de SQL/GQL.
- Preparación para la empresa: Se exploró cómo el MCP administrado proporciona una ruta escalable y autenticada para que los agentes de IA interactúen con los datos operativos.