1. Visão geral
O Spanner é um serviço de banco de dados totalmente gerenciado, escalonável horizontalmente e distribuído globalmente, ideal para cargas de trabalho operacionais relacionais e não relacionais. Além dos recursos principais, o Spanner oferece recursos avançados e poderosos que permitem criar aplicativos inteligentes e orientados por dados.
Este codelab se baseia no entendimento fundamental do Spanner e se aprofunda no uso das integrações avançadas para melhorar o processamento de dados e os recursos analíticos, usando um aplicativo de banco on-line como base.
Vamos nos concentrar em três recursos avançados principais:
- Integração com a Vertex AI:saiba como integrar o Spanner à plataforma de IA do Google Cloud, a Vertex AI. Você vai aprender a invocar modelos da Vertex AI diretamente de consultas SQL do Spanner, permitindo transformações e previsões eficientes no banco de dados. Assim, nosso aplicativo bancário pode categorizar transações automaticamente para casos de uso como acompanhamento de orçamento e detecção de anomalias.
- Pesquisa de texto completo:saiba como implementar a funcionalidade de pesquisa de texto completo no Spanner. Você vai explorar a indexação de dados de texto e escrever consultas eficientes para realizar pesquisas baseadas em palavras-chave nos seus dados operacionais, permitindo uma descoberta de dados eficiente, como encontrar clientes por endereço de e-mail no nosso sistema bancário.
- Consultas federadas do BigQuery:saiba como aproveitar os recursos de consulta federada do Spanner para consultar diretamente dados no BigQuery. Isso permite combinar os dados operacionais em tempo real do Spanner com os conjuntos de dados analíticos do BigQuery para insights e relatórios abrangentes sem duplicação de dados ou processos complexos de ETL, impulsionando vários casos de uso no nosso aplicativo bancário, como campanhas de marketing segmentadas, combinando dados do cliente em tempo real com tendências históricas mais amplas do BigQuery.
O que você vai aprender
- Como configurar uma instância do Spanner.
- Como criar um banco de dados e tabelas.
- Como carregar dados nas tabelas do banco de dados do Spanner.
- Como chamar modelos da Vertex AI no Spanner.
- Como consultar seu banco de dados do Spanner usando pesquisa aproximada e pesquisa de texto completo.
- Como executar consultas federadas no Spanner do BigQuery.
- Como excluir uma instância do Spanner.
O que é necessário
2. Configuração e requisitos
Criar um projeto
Se você já tiver um projeto na nuvem do Google Cloud com o faturamento ativado, clique no menu suspenso de seleção no canto superior esquerdo do console:
Com um projeto selecionado, pule para Ativar as APIs necessárias.
Se você ainda não tem uma Conta do Google (Gmail ou Google Apps), crie uma. Faça login no Console do Google Cloud Platform (console.cloud.google.com) e crie um projeto.
Clique no botão "NEW PROJECT" na caixa de diálogo exibida para criar um novo projeto:
Se você ainda não tiver um projeto, uma caixa de diálogo como esta será exibida para criar seu primeiro:
A caixa de diálogo de criação de projeto subsequente permite que você insira os detalhes do novo projeto.
Lembre-se do ID do projeto, um nome exclusivo em todos os projetos do Google Cloud. Faremos referência a ele mais adiante neste codelab como PROJECT_ID.
Em seguida, se ainda não tiver feito isso, ative o faturamento no Developers Console para usar os recursos do Google Cloud e ative a API Spanner, a API Vertex AI, a API BigQuery e a API BigQuery Connection.
Os preços do Spanner estão documentados aqui. Outros custos associados a outros recursos serão documentados nas páginas de preços específicas.
Novos usuários do Google Cloud Platform têm direito a uma avaliação sem custo financeiro de US$300.
Configuração do Google Cloud Shell
Neste codelab, vamos usar o Google Cloud Shell, um ambiente de linha de comando executado na nuvem.
O Cloud Shell é uma máquina virtual com base em Debian que contém todas as ferramentas de desenvolvimento necessárias. Ela oferece um diretório principal persistente de 5 GB, além de ser executada no Google Cloud. Isso aprimora o desempenho e a autenticação da rede. Isso significa que tudo que você precisa para este codelab é um navegador.
Para ativar o Cloud Shell no Console do Cloud, basta clicar em Ativar o Cloud Shell 
. Leva apenas alguns instantes para provisionar e se conectar ao ambiente.
Depois de se conectar ao Cloud Shell, você já estará autenticado e o projeto estará configurado com seu PROJECT_ID.
gcloud auth list
Saída esperada:
Credentialed Accounts ACTIVE: * ACCOUNT: <myaccount>@<mydomain>.com
gcloud config list project
Saída esperada:
[core] project = <PROJECT_ID>
Se, por algum motivo, o projeto não estiver definido, execute o seguinte comando:
gcloud config set project <PROJECT_ID>
Quer encontrar seu PROJECT_ID? Confira qual ID você usou nas etapas de configuração ou procure-o no painel do Console do Cloud:
O Cloud Shell também define algumas variáveis de ambiente por padrão, o que pode ser útil ao executar comandos futuros.
echo $GOOGLE_CLOUD_PROJECT
Saída esperada:
<PROJECT_ID>
Ative as APIs necessárias
Ative as APIs Spanner, Vertex AI e BigQuery para seu projeto:
gcloud services enable spanner.googleapis.com
gcloud services enable aiplatform.googleapis.com
gcloud services enable bigquery.googleapis.com
gcloud services enable bigqueryconnection.googleapis.com
Resumo
Nesta etapa, você configurou seu projeto, caso ainda não tivesse um, ativou o Cloud Shell e as APIs necessárias.
A seguir
Em seguida, configure a instância do Spanner.
3. Configurar uma instância do Spanner
Criar a instância do Spanner
Nesta etapa, você vai configurar uma instância do Spanner para o codelab. Para fazer isso, abra o Cloud Shell e execute este comando:
export SPANNER_INSTANCE=cloudspanner-onlinebanking
gcloud spanner instances create $SPANNER_INSTANCE \
--config=regional-us-central1 \
--description="Spanner Online Banking" \
--nodes=1 \
--edition=ENTERPRISE \
--default-backup-schedule-type=NONE
Saída esperada:
Creating instance...done.
Resumo
Nesta etapa, você criou a instância do Spanner.
A seguir
Em seguida, você vai preparar o aplicativo inicial e criar o banco de dados e o esquema.
4. Criar um banco de dados e um esquema
Preparar a inscrição inicial
Nesta etapa, você vai criar o banco de dados e o esquema usando o código.
Primeiro, crie um aplicativo Java chamado onlinebanking usando o Maven:
mvn -B archetype:generate \
-DarchetypeGroupId=org.apache.maven.archetypes \
-DgroupId=com.google.codelabs \
-DartifactId=onlinebanking \
-DjavaCompilerVersion=1.8 \
-DjunitVersion=4.13.2 \
-DarchetypeVersion=1.5
Faça o checkout e copie os arquivos de dados que vamos adicionar ao banco de dados. Consulte aqui para acessar o repositório de código:
git clone https://github.com/GoogleCloudPlatform/cloud-spanner-samples.git
cp -r ./cloud-spanner-samples/banking/data ./onlinebanking
Navegue até a pasta do aplicativo:
cd onlinebanking
Abra o arquivo pom.xml do Maven. Adicione a seção de gerenciamento de dependências para usar a BOM do Maven e gerenciar a versão das bibliotecas do Google Cloud:
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.google.cloud</groupId>
<artifactId>libraries-bom</artifactId>
<version>26.56.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
Esta é a aparência do editor e do arquivo: 
Verifique se a seção dependencies inclui as bibliotecas que o aplicativo vai usar:
<dependencies>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>4.13.2</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-nop</artifactId>
<version>2.0.9</version>
</dependency>
<dependency>
<groupId>com.opencsv</groupId>
<artifactId>opencsv</artifactId>
<version>5.10</version>
</dependency>
<dependency>
<groupId>com.google.cloud</groupId>
<artifactId>google-cloud-spanner</artifactId>
</dependency>
<dependency>
<groupId>com.google.cloud</groupId>
<artifactId>google-cloud-bigquery</artifactId>
</dependency>
<dependency>
<groupId>com.google.cloud</groupId>
<artifactId>google-cloud-bigqueryconnection</artifactId>
</dependency>
</dependencies>
Por fim, substitua os plug-ins de build para que o aplicativo seja empacotado em um JAR executável:
<build>
<plugins>
<plugin>
<artifactId>maven-resources-plugin</artifactId>
<version>3.3.1</version>
<executions>
<execution>
<id>copy-resources</id>
<phase>process-resources</phase>
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<outputDirectory>${project.build.directory}/${project.artifactId}-resources</outputDirectory>
<resources>
<resource>
<directory>resources</directory>
<filtering>true</filtering>
</resource>
</resources>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<version>3.8.1</version>
<executions>
<execution>
<id>copy-dependencies</id>
<phase>prepare-package</phase>
<goals>
<goal>copy-dependencies</goal>
</goals>
<configuration>
<outputDirectory>${project.build.directory}/${project.artifactId}-resources/lib</outputDirectory>
<overWriteReleases>false</overWriteReleases>
<overWriteSnapshots>false</overWriteSnapshots>
<overWriteIfNewer>true</overWriteIfNewer>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
<version>3.4.2</version>
<configuration>
<finalName>${project.artifactId}</finalName>
<outputDirectory>${project.build.directory}</outputDirectory>
<archive>
<index>false</index>
<manifest>
<mainClass>com.google.codelabs.App</mainClass>
<addClasspath>true</addClasspath>
<classpathPrefix>${project.artifactId}-resources/lib/</classpathPrefix>
</manifest>
</archive>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-failsafe-plugin</artifactId>
<version>3.2.5</version>
<executions>
<execution>
<goals>
<goal>integration-test</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>3.2.5</version>
<configuration>
<useSystemClassLoader>false</useSystemClassLoader>
</configuration>
</plugin>
</plugins>
</build>
Salve as mudanças feitas no arquivo pom.xml selecionando "Salvar" no menu "Arquivo" do editor do Cloud Shell ou pressionando Ctrl+S.
Agora que as dependências estão prontas, você vai adicionar código ao app para criar um esquema, alguns índices (incluindo pesquisa) e um modelo de IA conectado a um endpoint remoto. Você vai criar esses artefatos e adicionar mais métodos a essa classe ao longo deste codelab.
Abra App.java em onlinebanking/src/main/java/com/google/codelabs e substitua o conteúdo pelo seguinte código:
package com.google.codelabs;
import java.util.Arrays;
import java.util.List;
import java.util.concurrent.ExecutionException;
import com.google.api.gax.longrunning.OperationFuture;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.spanner.Database;
import com.google.cloud.spanner.DatabaseAdminClient;
import com.google.cloud.spanner.DatabaseClient;
import com.google.cloud.spanner.DatabaseId;
import com.google.cloud.spanner.Spanner;
import com.google.cloud.spanner.SpannerException;
import com.google.cloud.spanner.SpannerExceptionFactory;
import com.google.cloud.spanner.SpannerOptions;
import com.google.spanner.admin.database.v1.CreateDatabaseMetadata;
public class App {
// Create the Spanner database and schema
public static void create(DatabaseAdminClient dbAdminClient, DatabaseId db,
String location, String model) {
System.out.println("Creating Spanner database...");
List<String> statements = Arrays.asList(
"CREATE TABLE Customers (\n"
+ " CustomerId INT64 NOT NULL,\n"
+ " FirstName STRING(256) NOT NULL,\n"
+ " LastName STRING(256) NOT NULL,\n"
+ " FullName STRING(512) AS (FirstName || ' ' || LastName) STORED,\n"
+ " Email STRING(512) NOT NULL,\n"
+ " EmailTokens TOKENLIST AS\n"
+ " (TOKENIZE_SUBSTRING(Email, ngram_size_min=>2, ngram_size_max=>3,\n"
+ " relative_search_types=>[\"all\"])) HIDDEN,\n"
+ " Address STRING(MAX)\n"
+ ") PRIMARY KEY (CustomerId)",
"CREATE INDEX CustomersByEmail\n"
+ "ON Customers(Email)",
"CREATE SEARCH INDEX CustomersFuzzyEmail\n"
+ "ON Customers(EmailTokens)",
"CREATE TABLE Accounts (\n"
+ " AccountId INT64 NOT NULL,\n"
+ " CustomerId INT64 NOT NULL,\n"
+ " AccountType STRING(256) NOT NULL,\n"
+ " Balance NUMERIC NOT NULL,\n"
+ " OpenDate TIMESTAMP NOT NULL\n"
+ ") PRIMARY KEY (AccountId)",
"CREATE INDEX AccountsByCustomer\n"
+ "ON Accounts (CustomerId)",
"CREATE TABLE TransactionLedger (\n"
+ " TransactionId INT64 NOT NULL,\n"
+ " AccountId INT64 NOT NULL,\n"
+ " TransactionType STRING(256) NOT NULL,\n"
+ " Amount NUMERIC NOT NULL,\n"
+ " Timestamp TIMESTAMP NOT NULL"
+ " OPTIONS(allow_commit_timestamp=true),\n"
+ " Category STRING(256),\n"
+ " Description STRING(MAX),\n"
+ " CategoryTokens TOKENLIST AS (TOKENIZE_FULLTEXT(Category)) HIDDEN,\n"
+ " DescriptionTokens TOKENLIST AS (TOKENIZE_FULLTEXT(Description)) HIDDEN\n"
+ ") PRIMARY KEY (AccountId, TransactionId),\n"
+ "INTERLEAVE IN PARENT Accounts ON DELETE CASCADE",
"CREATE INDEX TransactionLedgerByAccountType\n"
+ "ON TransactionLedger(AccountId, TransactionType)",
"CREATE INDEX TransactionLedgerByCategory\n"
+ "ON TransactionLedger(AccountId, Category)",
"CREATE SEARCH INDEX TransactionLedgerTextSearch\n"
+ "ON TransactionLedger(CategoryTokens, DescriptionTokens)",
"CREATE MODEL TransactionCategoryModel\n"
+ "INPUT (prompt STRING(MAX))\n"
+ "OUTPUT (content STRING(MAX))\n"
+ "REMOTE OPTIONS (\n"
+ " endpoint = '//aiplatform.googleapis.com/projects/" + db.getInstanceId().getProject()
+ "/locations/" + location + "/publishers/google/models/" + model + "',\n"
+ " default_batch_size = 1\n"
+ ")");
OperationFuture<Database, CreateDatabaseMetadata> op = dbAdminClient.createDatabase(
db.getInstanceId().getInstance(),
db.getDatabase(),
statements);
try {
Database dbOperation = op.get();
System.out.println("Created Spanner database [" + dbOperation.getId() + "]");
} catch (ExecutionException e)