PolarDB:Search views and ETL stored procedures

Visão geral

O AutoETL é a capacidade integrada de sincronização de dados do PolarDB for MySQL. Ele permite o fluxo automático de dados entre diferentes tipos de nós no mesmo cluster. A versão atual suporta apenas a sincronização do PolarDB for MySQL para um nó PolarSearch no mesmo cluster, destinada a buscas e análises de alto desempenho.

O AutoETL oferece dois métodos para criar links de sincronização de dados:

• Search view: Utilize a sintaxe CREATE SEARCH VIEW para definir a lógica de sincronização de dados em SQL padrão. Ideal para a maioria dos cenários de sincronização de tabela única e agregação de múltiplas tabelas. O sistema gerencia automaticamente os detalhes subjacentes de conexão.

• Procedimento armazenado de ETL (dbms_etl.sync_by_sql): Use sintaxe compatível com Flink SQL para definir lógicas complexas de limpeza, transformação e agregação de dados por meio de procedimentos armazenados.

Escopo de aplicação

Antes de usar o AutoETL, certifique-se de que os seguintes requisitos sejam atendidos:

• Versão do cluster:

  • Search view:

    • MySQL 8.0.1. A versão de revisão deve ser 8.0.1.1.54 ou posterior.

    • MySQL 8.0.2. A versão de revisão deve ser 8.0.2.2.34 ou posterior.

  • Procedimento armazenado de ETL (sync_by_sql):

    • MySQL 8.0.1. A versão de revisão deve ser 8.0.1.1.52 ou posterior.

    • MySQL 8.0.2. A versão de revisão deve ser 8.0.2.2.33 ou posterior.

• Binlog: O cluster deve ter o Enable binary logging ativado.

• Direção da sincronização: Apenas sincronização do PolarDB for MySQL para um nó PolarSearch.

• Limitações de DDL: Ao executar operações DDL em tabelas de origem que possuem search views ou procedimentos armazenados de ETL, siga regras específicas para evitar interrupções na sincronização. Algumas alterações incompatíveis exigem a recriação da search view. Para mais informações, consulte DDL change rules and best practices.

• Tipos de dados: Não há suporte para sincronização do tipo BIT e tipos de dados espaciais como GEOMETRY, POINT, LINESTRING, POLYGON, MULTIPOINT, MULTILINESTRING, MULTIPOLYGON e GEOMETRYCOLLECTION.

• Limitações de consulta de search view: Atualmente, as search views suportam apenas a definição de semântica de sincronização e não permitem consultas de dados. Para consultar dados, conecte-se diretamente ao nó PolarSearch.

• Recursos de computação: O AutoETL utiliza CU como unidade de computação. Por padrão, o número de CUs em um cluster corresponde ao dobro da soma das CPUs de todos os nós do nó PolarSearch. É possível visualizar o uso atual de CUs do cluster na página Settings and Management > Search Management, na aba AutoETL.

Search views

Uma search view é um mecanismo declarativo de sincronização de dados fornecido pelo AutoETL. Utilize a sintaxe SQL padrão para criar uma search view; o sistema estabelece automaticamente um link contínuo de sincronização de dados da tabela de origem para o nó PolarSearch.

Criar uma search view

Sintaxe

CREATE SEARCH VIEW view_name [(column_list, PRIMARY KEY (pk_column_list))]
 [WITH (option_list)]
 AS select_statement;

Parâmetros

Parâmetro	Obrigatório	Descrição
view_name	Sim	Nome da search view, que também corresponde ao nome do índice de destino no nó PolarSearch.
column_list	Não	Define manualmente as colunas da search view. Separe múltiplas colunas com ,. Nota Na sincronização de tabela única, não é necessário especificar column_list. Os nomes originais das colunas da tabela de origem são usados por padrão.
pk_column_list	Não	Colunas de chave primária da search view. A estrutura corresponde ao mapeamento de índice do nó PolarSearch, portanto pk_column_list especifica o ID do documento de índice no nó PolarSearch. Se não for especificado, a primeira coluna de column_list será usada como ID do documento por padrão. Na sincronização de tabela única, a chave primária da tabela de origem é usada como ID do documento por padrão.
option_list	Não	Configuração de sincronização especificada explicitamente ao criar a search view, como paralelismo de sincronização, uso de recursos de computação por worker de sincronização e nome do índice de destino. Separe múltiplas configurações com ,. Se não especificado, os valores padrão do sistema serão utilizados. Para parâmetros e valores configuráveis, consulte AutoETL parameter configuration and best practices.
select_statement	Sim	Instrução SELECT que define a fonte de dados e a lógica de sincronização. Esta instrução recupera dados da tabela de origem e armazena o resultado no PolarSearch. Suporta consultas de tabela única, operações de JOIN, UNION ALL e GROUP BY entre múltiplas tabelas.

Limites de uso e observações

• A tabela de origem deve conter uma chave primária ou uma chave única.

• É necessária a permissão ALTER em todas as tabelas de origem na search view, além da permissão SELECT nas colunas relacionadas ou em toda a tabela.

• Após a criação de uma search view, novas colunas adicionadas à tabela de origem não são sincronizadas automaticamente. Para sincronizar novas colunas, consulte Modify a search view.

• Para usar uma configuração personalizada de índice de destino, crie primeiro o índice no nó PolarSearch, defina manualmente sua configuração e, em seguida, crie a search view. Caso o índice de destino não exista no momento da criação, o sistema o criará automaticamente.

• Para configurar parâmetros avançados de sincronização para agregação de múltiplas tabelas ou consultas complexas, como conversão de campos JSON e campos de roteamento, consulte AutoETL parameter configuration and best practices.

Preparação de dados

Crie os dados de teste usados nos exemplos a seguir executando as instruções SQL abaixo no PolarDB for MySQL.

CREATE DATABASE IF NOT EXISTS db1;
CREATE DATABASE IF NOT EXISTS db2;

USE db1;
CREATE TABLE IF NOT EXISTS t1 (
 id INT PRIMARY KEY,
 c1 VARCHAR(100),
 c2 VARCHAR(100)
);
INSERT INTO t1(id, c1, c2) VALUES
(1, 'apple', 'red'),
(2, 'banana', 'yellow'),
(3, 'grape', 'purple');

USE db2;
CREATE TABLE IF NOT EXISTS t2 (id INT PRIMARY KEY, c2 INT);
INSERT INTO t2(id, c2) VALUES (1, 111), (2, 222), (4, 444);

Exemplos

• Sincronização de tabela completa: Sincronize db1.t1 com o PolarSearch. O nome da view view_test também será o nome do índice de destino no PolarSearch.

  CREATE SEARCH VIEW view_test AS SELECT * FROM db1.t1;

• Sincronização de colunas específicas: Sincronize apenas as colunas c1 e c2, definindo manualmente os tipos de coluna e a chave primária.

  CREATE SEARCH VIEW view_test1 AS SELECT c1, c2 FROM db1.t1;

• Parâmetros de sincronização especificados: Especifique a configuração de sincronização através da cláusula WITH ao criar uma search view. O exemplo abaixo sincroniza as colunas c1 e c2 da tabela db1.t1 com o PolarSearch e define o paralelismo de sincronização como 2.

  CREATE SEARCH VIEW view_test6 WITH ('parallelism' = '2') AS SELECT c1, c2 FROM db1.t1;

• Sincronização com filtro condicional: Sincronize apenas os dados que atendem à condição WHERE.

  CREATE SEARCH VIEW view_test2 AS SELECT id, c1, c2 FROM db1.t1 WHERE c1 > 10;

• JOIN de múltiplas tabelas: Una db1.t1 e db2.t2 através de id e sincronize o resultado com o PolarSearch.

  CREATE SEARCH VIEW view_test3(id, c1, c2) AS SELECT t1.id, t1.c1, t2.c2 FROM db1.t1 AS t1 LEFT JOIN db2.t2 AS t2 ON t1.id = t2.id;

• UNION de múltiplas tabelas: Combine várias tabelas com a mesma estrutura e sincronize-as. Cada instrução SELECT deve ter o mesmo número e tipos de colunas.

  CREATE SEARCH VIEW view_test4(id, c2) AS SELECT id, c2 FROM db1.t1 UNION ALL SELECT id, c2 FROM db2.t2;

• Agregação agrupada: Sincronize dados após agregação por grupo. Ao usar GROUP BY, defina manualmente as colunas e a chave primária.

  CREATE SEARCH VIEW view_test5 (id, max_c) AS SELECT t1.id, MAX(t1.c1) AS max_c FROM db1.t1 GROUP BY t1.id;

Verificar dados

Verifique o status de sincronização da search view:

SHOW SEARCH VIEW STATUS;

Quando o status for active, a sincronização de dados da search view está operando normalmente. Conecte-se ao nó PolarSearch usando uma API REST compatível com Elasticsearch para validar os dados:

# Replace <user>:<password> with the PolarSearch node credentials and <polarsearch_endpoint> with the PolarSearch node endpoint and port
curl -u <user>:<password> -X GET "http://<polarsearch_endpoint>/view_test/_search"

Gerenciar search views

Utilize os comandos a seguir para visualizar search views criadas, ou para parar, reiniciar ou reconstruir a sincronização de dados. Todos os comandos devem ser executados em um cliente de banco de dados após conectar-se ao cluster.

Visualizar o status de todas as search views

SHOW SEARCH VIEW STATUS;

O resultado é apresentado conforme abaixo. Quando o status for active, a sincronização de dados da search view está operando normalmente.

+------------+--------+----------+---------+---------------------+---------------------+
| View Name | Type | Status | Message | Created_at | Updated_at |
+------------+--------+----------+---------+---------------------+---------------------+
| view_test | search | active | | 2026-03-18 18:44:12 | 2026-03-18 18:51:37 |
+------------+--------+----------+---------+---------------------+---------------------+

Visualizar a instrução CREATE de uma search view específica

SHOW CREATE SEARCH VIEW view_test;

O resultado é apresentado conforme abaixo:

+-----------+------------------------------------------------------+
| View Name | Create Search View |
+-----------+------------------------------------------------------+
| view_test | CREATE SEARCH VIEW view_test AS SELECT * FROM db1.t1 |
+-----------+------------------------------------------------------+

Parar uma search view

Caso precise modificar ou reconstruir o índice de destino no nó PolarSearch, pare a sincronização de dados da search view para evitar erros de gravação. Após concluir a modificação do índice no nó PolarSearch, reinicie a search view.

ALTER SEARCH VIEW view_test STOP;

Reiniciar uma search view

Reinicie uma search view parada ou em execução.

ALTER SEARCH VIEW view_test RESTART;

Reconstruir uma search view

Leia novamente todos os dados da tabela de origem e grave-os no nó PolarSearch.

Importante

• Uma reconstrução reexamina todos os dados na tabela de origem. Isso pode levar muito tempo se o volume de dados for grande.

• A reconstrução não limpa os dados de índice existentes no nó PolarSearch. Em vez disso, os dados são sobrescritos diretamente.

ALTER SEARCH VIEW view_test REBUILD;

Excluir uma search view

Importante

Excluir uma search view é uma operação de alto risco. Confirme antes de prosseguir. Esta operação interrompe a sincronização de dados da search view e limpa os recursos relacionados, mas não exclui os dados de índice no PolarSearch.

DROP SEARCH VIEW view_name;

O sistema trata a exclusão de maneira diferente dependendo do status da search view:

• Search view com status active: O status muda primeiro para dropping. Após o sistema concluir a limpeza de recursos e a exclusão dos dados do índice de destino, o status muda para dropped.

• Search view com status dropped: O sistema remove completamente as informações da search view.

• Search views em outros status: O sistema não suporta exclusão.

Modificar uma search view

Após criar uma search view, ajuste seus parâmetros de tempo de execução ou modifique sua lógica de sincronização, como adicionar campos de sincronização ou alterar condições de consulta. O AutoETL fornece três métodos de modificação:

• Para ajustar apenas parâmetros de tempo de execução, como paralelismo e uso de recursos de computação, use a Modificação de parâmetros. Não são necessárias alterações no SQL de sincronização.

• Ao modificar a lógica de sincronização, prefira a Modificação de SQL in-place. Se as definições SQL forem compatíveis, a sincronização continuará a partir do checkpoint original sem ressincronização completa. Consulte DDL change rules and best practices para determinar se as definições SQL são compatíveis.

• Se as definições SQL forem incompatíveis e a modificação in-place não for possível, utilize a modificação "novo índice + nova search view" para reconstruir.

Modificação de parâmetros

Para uma search view em execução, modifique seus parâmetros de tempo de execução usando a sintaxe a seguir. O AutoETL lê automaticamente a nova configuração e reinicia a search view.

Sintaxe

ALTER SEARCH VIEW view_name UPDATE WITH (new_option_list);

Exemplos

Ajuste o paralelismo para 8, CPU por worker para 4 e concorrência por worker para 8 na view_test:

ALTER SEARCH VIEW view_test UPDATE WITH ('parallelism' = '8', 'link.tm.cpu' = '4', 'link.tm.slots' = '8');

Modificação de SQL in-place

A modificação de SQL in-place altera diretamente o SQL de sincronização de uma search view existente sem criar um novo índice PolarSearch ou search view, nem alternar consultas de negócios, reduzindo o tempo de sincronização completa. Se as definições SQL forem compatíveis, a sincronização continua a partir do checkpoint original. Caso contrário, a modificação falha, e o sistema reverte automaticamente para a definição anterior à modificação e reinicia a search view.

Sintaxe

ALTER SEARCH VIEW view_name UPDATE
 [TO (column_list, PRIMARY KEY (pk_column_list))]
 AS new_select_statement;

Exemplos

• Sincronizar novas colunas da tabela de origem: Uma search view de tabela completa não sincroniza automaticamente novas colunas adicionadas à tabela de origem após a criação da view. Depois que a tabela de origem db1.t1 adicionar novas colunas, execute a seguinte instrução para sincronizar os dados da nova coluna com o PolarSearch.

  ALTER SEARCH VIEW view_test UPDATE;

• Ajustar colunas sincronizadas: Originalmente sincroniza as colunas c1 e c2. Altere para sincronizar apenas a coluna c1.

  ALTER SEARCH VIEW view_test UPDATE AS SELECT c1 FROM db1.t1;

• Ajustar condições de filtro: Altere a condição WHERE de c1 > 10 para c1 > 20.

  ALTER SEARCH VIEW view_test UPDATE AS SELECT id, c1, c2 FROM db1.t1 WHERE c1 > 20;

Modificação "novo índice + nova search view"

Se as definições SQL forem incompatíveis e a modificação in-place não for possível, use o método "novo índice + nova search view" para reconstruir, garantindo que as consultas de negócios não sejam afetadas.

1. Crie uma nova search view e sincronize com um novo índice PolarSearch.

2. Use SHOW SEARCH VIEW STATUS para verificar o status da nova search view. Quando a latência de sincronização cair para 0 a 1 segundo, alterne a lógica de consulta de negócios do índice antigo para o novo índice.

3. Exclua a search view antiga.

Para obter detalhes sobre o impacto das alterações DDL da tabela de origem nas search views e práticas detalhadas de modificação, consulte DDL change rules and best practices.

Procedimento armazenado de ETL (sync_by_sql)

Para cenários que exigem transformação, agregação ou computação complexa, utilize o procedimento armazenado CALL dbms_etl.sync_by_sql para definir a lógica de sincronização de dados usando sintaxe compatível com Flink SQL.

Criar um link de sincronização

Sintaxe

Nota

Antes de chamar dbms_etl.sync_by_sql, utilize as variáveis de sessão (como AutoETL parameter configuration and best practices) de esl_link_options e esl_sink_options para definir a configuração de sincronização do link. O mecanismo AutoETL lê automaticamente essas variáveis ao criar o link.

CALL dbms_etl.sync_by_sql("search", "<sync_sql>");

Exemplos

Nota

As informações de conexão para as tabelas de origem e destino, como endereços de host, portas e credenciais, são configuradas automaticamente pelo sistema. Não é necessário especificá-las manualmente na cláusula WITH.

CALL dbms_etl.sync_by_sql("search", "

-- Step 1: Define the PolarDB source table
CREATE TEMPORARY TABLE `db1`.`t1` (
 `id` BIGINT,
 `c1` STRING,
 PRIMARY KEY (`id`) NOT ENFORCED
) WITH (
 'connector' = 'mysql',
 'database-name' = 'db1',
 'table-name' = 't1'
);

-- Step 2: Define the PolarSearch destination table
CREATE TEMPORARY TABLE `dest` (
 `id` BIGINT,
 `max_c` STRING,
 PRIMARY KEY (`id`) NOT ENFORCED
) WITH (
 'connector' = 'opensearch',
 'index' = 'dest'
);

-- Step 3: Define the computation and insert logic
INSERT INTO `dest`
SELECT
 `t1`.`id`,
 MAX(`t1`.`c1`)
FROM `db1`.`t1` AS `t1`
GROUP BY `t1`.`id`;
");

Verificar dados

Conecte-se ao nó PolarSearch usando uma API REST compatível com Elasticsearch para consultar e verificar se os dados foram sincronizados.

# Replace <polarsearch_endpoint> with the PolarSearch node endpoint
curl -u <user>:<password> -X GET "http://<polarsearch_endpoint>/dest/_search"

Gerenciar links de sincronização

Utilize os comandos a seguir para visualizar links de sincronização criados, ou para parar, reiniciar ou reconstruir a sincronização de dados. Todos os comandos devem ser executados em um cliente de banco de dados após conectar-se ao cluster.

Visualizar todos os links

CALL dbms_etl.show_sync_link();

Visualizar um link específico por ID

Substitua <sync_id> pelo ID retornado quando o link foi criado.

CALL dbms_etl.show_sync_link_by_id('<sync_id>')\G

Descrição do resultado retornado:

*************************** 1. row ***************************
 SYNC_ID: crb5rmv8rttsg
 NAME: crb5rmv8rttsg
 SYSTEM: search
SYNC_DEFINITION: db1.t1 -> dest
 SOURCE_TABLES: db1.t1
 SINK_TABLES: dest
 STATUS: active -- Link status. active indicates normal operation
 MESSAGE: -- If an error occurs, the error message is displayed here
 CREATED_AT: 2024-05-20 11:55:06
 UPDATED_AT: 2024-05-20 17:28:04
 OPTIONS:...

Parar um link

Caso precise modificar ou reconstruir o índice de destino no nó PolarSearch, pare o link de sincronização para evitar erros de gravação. Após concluir a modificação do índice no nó PolarSearch, reinicie o link.

CALL dbms_etl.stop_sync_link('<sync_id>');

Reiniciar um link

Reinicie um link de sincronização parado ou em execução.

CALL dbms_etl.restart_sync_link('<sync_id>');

Reconstruir um link

Leia novamente todos os dados da tabela de origem e grave-os no nó PolarSearch. Uma reconstrução reexamina todos os dados na tabela de origem. Isso pode levar muito tempo se o volume de dados for grande. A reconstrução não limpa os dados de índice existentes no nó PolarSearch. Em vez disso, os dados são sobrescritos diretamente.

CALL dbms_etl.rebuild_sync_link('<sync_id>');

Excluir um link de sincronização

Esta operação interrompe a sincronização de dados e limpa os recursos relacionados.

Importante

Excluir um link de sincronização é uma operação de alto risco. Confirme antes de prosseguir. Esta operação interrompe a sincronização de dados do link e limpa os recursos relacionados, mas não exclui os dados de índice no PolarSearch.

CALL dbms_etl.drop_sync_link('<sync_id>');

O sistema trata a exclusão via drop_sync_link de maneira diferente dependendo do status do link:

• Link com status active: O status muda primeiro para dropping. Após o sistema concluir a limpeza dos recursos do link e dos dados do índice de destino, o status muda para dropped.

• Link com status dropped: O sistema remove completamente as informações do link.

• Links em outros status: O sistema não suporta exclusão.

Modificar um link de sincronização

Após criar um link de sincronização, ajuste seus parâmetros de tempo de execução ou modifique seu SQL de sincronização. Assim como nas search views, o AutoETL fornece três métodos de modificação:

• Para ajustar apenas parâmetros de tempo de execução, como paralelismo e uso de recursos de computação, use a Modificação de parâmetros. Não são necessárias alterações no SQL de sincronização.

• Ao modificar o SQL de sincronização, prefira a Modificação de SQL in-place. Se as definições SQL forem compatíveis, a sincronização continuará a partir do checkpoint original sem ressincronização completa. Consulte DDL change rules and best practices para determinar se as definições SQL são compatíveis.

• Se as definições SQL forem incompatíveis e a modificação in-place não for possível, utilize a modificação "novo índice + novo link" para reconstruir.

Modificação de parâmetros

Para um link de sincronização em execução, defina primeiro a nova configuração do link através da variável de sessão esl_link_options e, em seguida, chame dbms_etl.update_sync_link para aplicar a configuração. O AutoETL lê automaticamente a nova configuração de esl_link_options e reinicia o link de sincronização.

Sintaxe

SET esl_link_options = "<new_option_list>";
CALL dbms_etl.update_sync_link('<sync_id>', '');

Exemplos

Ajuste o paralelismo para 8, CPU por worker para 4 e concorrência por worker para 8 no link 8f4228x2uq12z:

SET esl_link_options = "'parallelism' = '8', 'link.tm.cpu' = '4', 'link.tm.slots' = '8'";
CALL dbms_etl.update_sync_link('8f4228x2uq12z', '');

Modificação de SQL in-place

A modificação de SQL in-place altera diretamente o SQL de sincronização de um link existente sem criar um novo índice PolarSearch ou link, nem alternar consultas de negócios, reduzindo o tempo de sincronização completa. Se as definições SQL forem compatíveis antes e depois da modificação, a sincronização continua a partir do checkpoint original; caso não sejam compatíveis, a modificação falha, o sistema reverte automaticamente para a definição de sincronização anterior à modificação e reinicia o link.

Sintaxe

<new_sync_sql> requer o novo SQL de sincronização completo. Sua estrutura é a mesma do SQL de sincronização em dbms_etl.sync_by_sql usado quando o link foi criado.

CALL dbms_etl.update_sync_link('<sync_id>', '<new_sync_sql>');

Exemplos

Altere a condição de filtro para c1 > 20 no link 8f4228x2uq12z:

CALL dbms_etl.update_sync_link('8f4228x2uq12z', "

CREATE TEMPORARY TABLE `db1`.`t1` (
 `id` BIGINT,
 `c1` STRING,
 PRIMARY KEY (`id`) NOT ENFORCED
) WITH (
 'connector' = 'mysql',
 'database-name' = 'db1',
 'table-name' = 't1'
);

CREATE TEMPORARY TABLE `dest` (
 `id` BIGINT,
 `c1` STRING,
 PRIMARY KEY (`id`) NOT ENFORCED
) WITH (
 'connector' = 'opensearch',
 'index' = 'dest'
);

INSERT INTO `dest` SELECT `id`, `c1` FROM `db1`.`t1` WHERE `c1` > 20;
");

Modificação "novo índice + novo link"

Se as definições SQL forem incompatíveis e a modificação in-place não for possível, use o método "novo índice + novo link" para reconstruir, garantindo que as consultas de negócios não sejam afetadas. Tome como exemplo a modificação do link A:

1. Crie o link B com base no novo SQL de sincronização e sincronize com um novo índice PolarSearch.

2. Use CALL dbms_etl.show_sync_link_by_id('<sync_id>') para verificar o status do link B. Quando a latência de sincronização do link B cair para 0 a 1 segundo, alterne a lógica de consulta de negócios do índice antigo para o novo índice.

3. Após confirmar que o link B está operando de forma estável, execute CALL dbms_etl.drop_sync_link('<sync_id>') para excluir o link A antigo.

Perguntas frequentes

Quais são as diferenças entre search views e procedimentos armazenados de ETL (sync_by_sql)?

As principais diferenças residem nos cenários de uso e na complexidade:

• Search views: Usa sintaxe SQL padrão (CREATE SEARCH VIEW). O sistema gerencia automaticamente os detalhes subjacentes de conexão e sincronização. Não é necessário escrever Flink SQL. Adequado para a maioria dos cenários de sincronização de tabela única e agregação de múltiplas tabelas.

• Procedimento armazenado de ETL: Usa sintaxe compatível com Flink SQL (CALL dbms_etl.sync_by_sql). Recomendado para cenários que exigem limpeza, transformação e agregação complexa de dados, oferecendo capacidades completas de controle do Flink SQL. A configuração de conexão para tabelas de origem e destino é gerenciada automaticamente pelo sistema.