Tabelas de sistema do Paimon - Realtime Compute for Apache Flink: Central de Documentação do Alibaba Cloud

O Apache Paimon utiliza tabelas de sistema para expor metadados e informações sobre o consumo de dados de cada tabela Paimon. Consulte essas tabelas com SQL para inspecionar snapshots, histórico de schema, partições, arquivos e tags, ou para consumir dados de alteração de forma mais eficiente.

As tabelas de sistema dividem-se em duas categorias:

Tabelas de metadados — snapshots, schemas, options, partitions, files, tags
Tabelas de consumo de dados — tabela otimizada para leitura, tabela de log de auditoria

Tabelas de metadados

Tabela de snapshots

A tabela de snapshots ($snapshots) registra informações sobre cada snapshot, incluindo seu ID, horário de criação e contagem de registros.

SELECT * FROM mycatalog.mydb.`mytbl$snapshots`;

Coluna	Tipo de dado	Descrição
`snapshot_id`	Long	ID do snapshot.
`schema_id`	Long	ID do schema utilizado por este snapshot. Faça uma referência cruzada com a tabela de schemas para obter as definições dos campos.
`commit_time`	Timestamp	Horário em que o snapshot foi criado.
`total_record_count`	Long	Total de registros nos arquivos de dados apontados por este snapshot.
`delta_record_count`	Long	Registros adicionados em comparação ao snapshot anterior.
`changelog_record_count`	Long	Registros de changelog gerados em comparação ao snapshot anterior.

O valor de total_record_count não reflete a contagem lógica de registros na tabela Paimon. Os arquivos de dados passam por compactação em memória antes de serem capturados em um snapshot.

Tabela de schemas

A tabela de schemas ($schemas) registra todas as versões de schema de uma tabela Paimon. Sempre que você modifique o schema usando ALTER TABLE, CREATE TABLE AS ou CREATE DATABASE AS, um novo registro é gravado nesta tabela.

SELECT * FROM mycatalog.mydb.`mytbl$schemas`;

Coluna	Tipo de dado	Descrição
`schema_id`	Long	ID da versão do schema.
`fields`	String	Nome e tipo de dado de cada coluna.
`partition_keys`	String	Nome da chave de partição.
`primary_keys`	String	Nome da chave primária.
`options`	String	Valores atuais das opções da tabela.
`comment`	String	Comentário sobre a tabela.
`update_time`	Timestamp	Horário da última modificação do schema.

Tabela de options

A tabela de options ($options) exibe a configuração atual de todas as opções da tabela definidas explicitamente.

SELECT * FROM mycatalog.mydb.`mytbl$options`;

Coluna	Tipo de dado	Descrição
`key`	String	Nome da opção da tabela.
`value`	String	Valor da opção da tabela.

As opções não listadas nesta tabela estão utilizando seus valores padrão.

Tabela de partitions

A tabela de partitions ($partitions) mostra as partições de uma tabela Paimon, juntamente com suas contagens de registros e tamanhos totais de arquivo.

SELECT * FROM mycatalog.mydb.`mytbl$partitions`;

Coluna	Tipo de dado	Descrição
`partition`	String	Partição no formato `[partition value 1, partition value 2, ...]`.
`record_count`	Long	Total de registros na partição.
`file_size_in_bytes`	Long	Tamanho total dos arquivos na partição, em bytes. Apenas os arquivos de dados do snapshot atual são contabilizados.

O valor de record_count não reflete a contagem lógica de registros. Os arquivos de dados passam por compactação em memória antes de serem capturados em um snapshot.

Tabela de files

A tabela de files ($files) lista todos os arquivos de dados apontados pelo snapshot atual, incluindo formato, contagem de registros e tamanho.

Consulte os arquivos do snapshot mais recente:

SELECT * FROM mycatalog.mydb.`mytbl$files`;

Consulte os arquivos de um snapshot específico (por exemplo, snapshot com ID 5):

SELECT * FROM mycatalog.mydb.`mytbl$files` /*+ OPTIONS('scan.snapshot-id'='5') */;

Coluna	Tipo de dado	Descrição
`partition`	String	Partição que contém o arquivo, no formato `[partition value 1, partition value 2, ...]`.
`bucket`	Integer	Bucket que contém o arquivo. Aplica-se apenas a tabelas de chave primária que utilizam o modo de bucket fixo.
`file_path`	String	Caminho do arquivo.
`file_format`	String	Formato do arquivo.
`schema_id`	Long	ID do schema utilizado por este arquivo. Faça uma referência cruzada com a tabela de schemas para obter as definições dos campos.
`level`	Integer	Nível da árvore de mesclagem estruturada em log (LSM) do arquivo. Aplica-se apenas a tabelas de chave primária. Um valor `0` indica um arquivo pequeno — monitore esta coluna para acompanhar o progresso da compactação em um bucket.
`record_count`	Long	Número de registros no arquivo.
`file_size_in_bytes`	Long	Tamanho do arquivo, em bytes.

A tabela de files abrange apenas os arquivos de dados presentes no snapshot consultado. Arquivos de dados históricos não referenciados por esse snapshot não são incluídos.

Tabela de tags

A tabela de tags ($tags) registra informações sobre as tags, incluindo o snapshot associado a cada uma delas.

SELECT * FROM mycatalog.mydb.`mytbl$tags`;

Coluna	Tipo de dado	Descrição
`tag_name`	String	Nome da tag.
`snapshot_id`	Long	ID do snapshot associado à tag.
`schema_id`	Long	ID do schema utilizado pela tag. Faça uma referência cruzada com a tabela de schemas para obter as definições dos campos.
`commit_time`	Timestamp	Horário de criação do snapshot associado.
`record_count`	Long	Número de registros nos arquivos de dados.

Tabelas de consumo de dados

Tabela otimizada para leitura

Se você utiliza uma tabela de chave primária e deseja melhorar a eficiência de leituras em lote ou consultas OLAP ad hoc, consuma dados da tabela otimizada para leitura ($ro). Diferentemente de uma consulta direta à tabela, que compacta arquivos de dados em memória antes de retornar resultados, a tabela $ro ignora essa etapa ao verificar apenas arquivos já compactados. Isso elimina a sobrecarga de compactação e acelera as leituras, mas os resultados podem não incluir os arquivos pequenos mais recentes ainda não compactados.

Para compactar arquivos pequenos em intervalos regulares e equilibrar throughput de escrita, desempenho de leitura e latência de dados, defina o seguinte parâmetro:

Parâmetro	Tipo de dado	Padrão	Descrição
`compaction.optimization-interval`	Duration	Nenhum	Intervalo para compactação de arquivos pequenos. Defina este valor como superior a `30 min` para evitar impactos no throughput de escrita.

SELECT * FROM mycatalog.mydb.`mytbl$ro`;

Tabela de log de auditoria

Utilize a tabela de log de auditoria ($audit_log) quando precisar rastrear o tipo exato de operação por trás de cada registro — por exemplo, para depurar alterações inesperadas nos dados ou crie pipelines downstream de dados de alteração.

Em comparação à tabela original, a tabela de log de auditoria insere uma coluna rowkind no início de cada registro para indicar o tipo de operação:

Valor de `rowkind`	Operação
`+I`	Inserção
`-U`	Atualização (antes)
`+U`	Atualização (depois)
`-D`	Exclusão

Todos os registros retornados pela tabela de log de auditoria possuem um rowkind igual a +I (inserção), pois a própria tabela apenas acrescenta registros.

SELECT * FROM mycatalog.mydb.`mytbl$audit_log`;

Referências

Para consultar a estrutura completa de cada tabela de sistema, consulte a documentação do Apache Paimon.