Ler informações de estado de Fluxo estruturado

No Databricks Runtime 14.3 LTS e posteriores, você pode usar operações DataFrame ou funções de valor de tabela do SQL para consultar metadados e dados de estado de Streaming Estruturado. Você pode usar essas funções para observar informações de estado para consultas com estado de Streaming Estruturado, que podem ser úteis para monitoramento e depuração.

Você precisa ter acesso de leitura ao caminho do ponto de verificação de uma consulta de streaming para consultar dados de estado ou metadados. As funções descritas neste artigo fornecem acesso somente leitura a dados de estado e metadados. Você só pode usar a semântica de leitura em lote para consultar informações de estado.

Observação

Não é possível consultar informações de estado para pipelines de Delta Live Tables, tabelas de streaming ou exibições materializadas.

Ler o repositório de estado de Streaming Estruturado

Você pode ler as informações do repositório de estado para consultas de Streaming Estruturado executadas em qualquer Databricks Runtime com suporte. Use a seguinte sintaxe:

Python

df = (spark.read
  .format("statestore")
  .load("/checkpoint/path"))

SQL

SELECT * FROM read_statestore('/checkpoint/path')

As seguintes configurações opcionais são compatíveis:

Opção	Tipo	Valor padrão	Descrição
batchId	Long	ID do lote mais recente	Representa o lote de destino para leitura. Especifique essa opção para consultar informações de estado para um estado anterior da consulta. O lote deve ser confirmado, mas ainda não deve ser limpo.
operatorId	Long	0	Representa o operador de destino para leitura. Essa opção é usada quando a consulta está usando vários operadores com estado.
storeName	String	“DEFAULT”	Representa o nome do repositório do estado de destino para leitura. Essa opção é usada quando o operador com estado usar várias instâncias de armazenamento de estado. O storeName ou joinSide deve ser especificado para uma junção stream-steam, mas não ambos.
joinSide	Cadeia de caracteres (“left” ou “right”)		Representa o lado de destino a ser lido. Essa opção é usada quando os usuários desejam ler o estado da junção entre fluxo e fluxo.

Os dados retornados têm o seguinte esquema:

Coluna	Tipo	Descrição
key	Struct (tipo adicional derivado da chave de estado)	A chave de um registro do operador com estado no ponto de verificação de estado.
value	Struct (tipo adicional derivado do valor de estado)	O valor de um registro do operador com estado no ponto de verificação de estado.
partition_id	Inteiro	A partição do ponto de verificação de estado que contém o registro de operador com estado.

Ler metadados de estado de Streaming Estruturado

Importante

Você precisa executar consultas de streaming no Databricks Runtime 14.2 ou superior para registrar metadados de estado. Os arquivos de metadados de estado não comprometem a compatibilidade com versões anteriores. Se você optar por executar uma consulta de streaming no Databricks Runtime 14.1 ou anterior, arquivos de metadados existentes serão ignorados e nenhum novo arquivo de metadados de estado será gravado.

Você pode ler as informações de metadados de estado para consultas de Streaming Estruturado executadas no Databricks Runtime 14.2 e posteriores. Use a seguinte sintaxe:

Python

df = (spark.read
  .format("state-metadata")
  .load("<checkpointLocation>"))

SQL

SELECT * FROM read_state_metadata('/checkpoint/path')

Os dados retornados têm o seguinte esquema:

Coluna	Tipo	Descrição
operatorId	Inteiro	A ID de inteiro do operador de streaming com estado.
operatorName	Inteiro	Nome do operador de streaming com estado.
stateStoreName	String	Nome do repositório de estado do operador.
numPartitions	Inteiro	Número de partições do repositório de estado.
minBatchId	Long	A ID mínima do lote disponível para o estado de consulta.
maxBatchId	Long	A ID máxima do lote disponível para consultar o estado.

Observação

Os valores de ID do lote fornecidos por minBatchId e maxBatchId refletem o estado no momento em que o ponto de verificação foi gravado. Lotes antigos são limpos automaticamente com execução de microlotes, então não há garantia que o valor fornecido aqui ainda esteja disponível.