Use tabelas online para servir recursos em tempo real

Visualização

As tabelas on-line estão em visualização pública. Durante a visualização, a ingestão de dados em Online Tables consome DBUs do SQL serverless. Os preços finais das mesas on-line serão disponibilizados em uma data futura.

A visualização de tabelas on-line está disponível nas seguintes regiões: us-east-1, us-west-2, eu-west-1, ap-southeast-2.

Uma tabela on-line é uma cópia somente leitura de uma tabela Delta que é armazenada em um formato orientado por linha otimizado para acesso on-line. As tabelas on-line são totalmente serverless que escalonam automaticamente a capacidade da taxa de transferência com a carga da solicitação e fornecem baixa latência e acesso de alta taxa de transferência a dados de qualquer escala. As tabelas on-line são projetadas para funcionar com os aplicativos Mosaic AI Model Serving, Feature Serving e retrieval-augmented generation (RAG), onde são usadas para pesquisas rápidas de dados.

O senhor também pode usar tabelas on-line em consultas usando lakehouse Federation. Ao usar a Federação lakehouse, o senhor deve usar um serverless SQL warehouse para acessar as tabelas on-line. Somente operações de leitura (SELECT) são suportadas. Esse recurso destina-se apenas a fins interativos ou de depuração e não deve ser usado para cargas de trabalho de produção ou de missão crítica.

A criação de uma tabela on-line usando a interface do usuário do Databricks é um processo de uma etapa. Basta selecionar a tabela Delta no Catalog Explorer e selecionar Create online table (Criar tabela on-line). O senhor também pode usar a API REST ou o SDK da Databricks para criar e gerenciar tabelas on-line. Consulte Trabalhar com tabelas on-line usando APIs.

Requisitos

O workspace deve estar habilitado para o Unity Catalog. Siga a documentação para criar um metastore Unity Catalog , habilitá-lo em um workspace e criar um catálogo.
Um modelo deve ser registrado no Unity Catalog para acessar as tabelas on-line.
Um administrador do Databricks deve aceitar os Termos de serviço serverless no console account .

Trabalhar com tabelas on-line usando a interface do usuário

Esta seção descreve como criar e excluir tabelas online e como verificar o status e acionar atualizações de tabelas online.

Criar uma tabela on-line usando a interface do usuário

O senhor cria uma tabela on-line usando o Catalog Explorer. Para obter informações sobre as permissões necessárias, consulte Permissões do usuário.

Para criar uma tabela online, a tabela Delta de origem deve ter uma key primária. Se a tabela Delta que você deseja usar não tiver uma key primária, crie uma seguindo estas instruções: Use uma tabela Delta existente no Unity Catalog como uma tabela de recursos.
No Catalog Explorer, navegue até a tabela de origem que o senhor deseja sincronizar com uma tabela on-line. No menu Create (Criar ), selecione Online table (Tabela on-line).

Use os seletores na caixa de diálogo para configurar a tabela online.

configurar caixa de diálogo de tabela on-line

Nome: nome a ser usado para a tabela online no Unity Catalog.

keyprimária: Coluna(s) na tabela de origem para usar como key(s) primária(s) na tabela online.

keyda série temporal: (opcional). Coluna na tabela de origem para usar como key de série temporal. Quando especificada, a tabela on-line inclui apenas a linha com o valor key série temporal mais recente para cada key primária.

Modo de sincronização: especifica como o pipeline de sincronização atualiza a tabela online. Selecione um entre Snapshot, Acionado ou Contínuo.

Política	Descrição
Snapshot	A execução do pipeline uma vez para obter um Snapshot da tabela de origem e copiá-lo para a tabela online. As alterações subsequentes na tabela de origem são refletidas automaticamente na tabela on-line, obtendo um novo Snapshot da origem e criando uma nova cópia. O conteúdo da tabela online é atualizado atomicamente.
Acionado	A execução do pipeline uma vez para criar uma cópia inicial do Snapshot da tabela de origem na tabela online. Ao contrário do modo de sincronização Snapshot , quando a tabela online é atualizada, apenas as alterações desde a última execução do pipeline são recuperadas e aplicadas à tabela online. A refresh incremental pode ser acionada manualmente ou automaticamente de acordo com um programar.
Contínuo	A execução do pipeline continuamente. As alterações subsequentes na tabela de origem são aplicadas de forma incremental à tabela online em modo de transmissão em tempo real. Nenhuma refresh manual é necessária.

Observação

Para dar suporte ao modo de sincronização Acionado ou Contínuo , a tabela de origem deve ter Alterar feed de dados habilitado.

Quando terminar, clique em Confirmar. A página da tabela online é exibida.
A nova tabela online é criada no catálogo, esquema e nome especificados na caixa de diálogo de criação. No Catalog Explorer, a tabela online é indicada por .

Obter status e acionar atualizações usando a interface do usuário

Para verificar o status da tabela online, clique no nome da tabela no Catálogo para abri-la. A página da tabela online aparece com a Visão geral tab aberta. A seção Data Ingest mostra o status da atualização mais recente. Para acionar uma atualização, clique em Sincronizar agora. A seção Data Ingest também inclui um link para o pipeline Delta Live Tables que atualiza a tabela.

view da página da tabela on-line no catálogo

Excluir uma tabela on-line usando a interface do usuário

Na página da tabela on-line, selecione Excluir na lista cardápio de quibe.

Trabalhar com tabelas on-line usando APIs

O senhor também pode usar o SDK da Databricks ou a API REST para criar e gerenciar tabelas on-line.

Para obter informações de referência, consulte a documentação de referência do Databricks SDK para Python ou a API REST.

Requisitos

Databricks SDK versão 0.20 ou superior.

Criar uma tabela on-line usando APIs

from pprint import pprint
from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import *

w = WorkspaceClient(host='https://xxx.databricks.com', token='xxx')

# Create an online table
spec = OnlineTableSpec(
  primary_key_columns=["pk_col"],
  source_table_full_name="main.default.source_table",
  run_triggered=OnlineTableSpecTriggeredSchedulingPolicy.from_dict({'triggered': 'true'})
)

w.online_tables.create(name='main.default.my_online_table', spec=spec)

curl --request POST "https://xxx.databricks.com/api/2.0/online-tables" \
--header "Authorization: Bearer xxx" \
--data '{
    "name": "main.default.my_online_table",
    "spec": {
        "run_triggered": {},
        "source_table_full_name": "main.default.source_table",
        "primary_key_columns": ["a"]
    }
  }'

A tabela on-line começa a ser sincronizada automaticamente após ser criada.

Obter status e acionar a atualização usando APIs

O senhor pode acessar view o status e a especificação da tabela on-line seguindo o exemplo abaixo. Se a sua tabela on-line não for contínua e o senhor quiser acionar um refresh manual de seus dados, poderá usar a API do pipeline para fazer isso.

Use o ID do pipeline associado à tabela on-line na especificação da tabela on-line e comece uma nova atualização no pipeline para acionar o refresh. Isso é equivalente a clicar em Sync now (Sincronizar agora ) na interface do usuário da tabela on-line no Catalog Explorer.

pprint(w.online_tables.get('main.default.my_online_table'))

# Sample response
OnlineTable(name='main.default.my_online_table',
    spec=OnlineTableSpec(perform_full_copy=None,
        pipeline_id='some-pipeline-id',
        primary_key_columns=['pk_col'],
        run_continuously=None,
        run_triggered={},
        source_table_full_name='main.default.source_table',
        timeseries_key=None),
    status=OnlineTableStatus(continuous_update_status=None,
        detailed_state=OnlineTableState.PROVISIONING,
        failed_status=None,
        message='Online Table creation is '
            'pending. Check latest status in '
            'Delta Live Tables: '
            'https://xxx.databricks.com/pipelines/some-pipeline-id',
        provisioning_status=None,
        triggered_update_status=None))

# Trigger an online table refresh by calling the pipeline API. To discard all existing data
# in the online table before refreshing, set "full_refresh" to "True". This is useful if your
# online table sync is stuck due to, for example, the source table being deleted and recreated
# with the same name while the sync was running.
w.pipelines.start_update(pipeline_id='some-pipeline-id', full_refresh=True)

curl --request GET \
  "https://xxx.databricks.com/api/2.0/online-tables/main.default.my_online_table" \
  --header "Authorization: Bearer xxx"

# Sample response
{
  "name": "main.default.my_online_table",
  "spec": {
    "run_triggered": {},
    "source_table_full_name": "main.default.source_table",
    "primary_key_columns": ["pk_col"],
    "pipeline_id": "some-pipeline-id"
  },
  "status": {
    "detailed_state": "PROVISIONING",
    "message": "Online Table creation is pending. Check latest status in Delta Live Tables: https://xxx.databricks.com#joblist/pipelines/some-pipeline-id"
  }
}

# Trigger an online table refresh by calling the pipeline API. To discard all existing data
# in the online table before refreshing, set "full_refresh" to "True". This is useful if your
# online table sync is stuck due to, for example, the source table being deleted and recreated
# with the same name while the sync was running.
curl --request POST "https://xxx.databricks.com/api/2.0/pipelines/some-pipeline-id/updates" \
  --header "Authorization: Bearer xxx" \
  --data '{
    "full_refresh": true
  }'

Excluir uma tabela on-line usando APIs

w.online_tables.delete('main.default.my_online_table')

curl --request DELETE \
  "https://xxx.databricks.com/api/2.0/online-tables/main.default.my_online_table" \
  --header "Authorization: Bearer xxx"

A exclusão da tabela on-line interrompe qualquer sincronização de dados em andamento e libera todos os seus recursos.

Servir tabela online uso de dados a recurso servindo endpoint

Para modelos e aplicativos hospedados fora do Databricks, você pode criar um endpoint de serviço de recurso para servir recurso de tabelas online. O endpoint disponibiliza o recurso em baixa latência utilizando uma API REST.

Crie uma especificação de recurso.

Ao criar uma especificação de recurso, você especifica a tabela Delta de origem. Isso permite que a especificação do recurso seja usada em cenários offline e online. Para pesquisas on-line, o endpoint de serviço usa automaticamente a tabela on-line para realizar pesquisas de recursos de baixa latência.

A tabela Delta de origem e a tabela online devem usar a mesma key primária.

A especificação do recurso pode ser view na Função tab no Catalog Explorer.
```
from databricks.feature_engineering import FeatureEngineeringClient, FeatureLookup

fe = FeatureEngineeringClient()
fe.create_feature_spec(
  name="catalog.default.user_preferences_spec",
  features=[
    FeatureLookup(
      table_name="user_preferences",
      lookup_key="user_id"
    )
  ]
)
```

Crie um endpoint de atendimento de recursos.

Esta etapa pressupõe que você criou uma tabela on-line chamada user_preferences_online_table que sincroniza dados da tabela Delta user_preferences. Use a especificação do recurso para criar um endpoint de atendimento de recursos. O endpoint disponibiliza dados por meio de uma API REST usando a tabela online associada.

Observação

O usuário que realiza essas operações deverá ser o proprietário tanto da mesa offline quanto da mesa online.

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.serving import EndpointCoreConfigInput, ServedEntityInput

workspace = WorkspaceClient()

# Create endpoint
endpoint_name = "fse-location"

workspace.serving_endpoints.create_and_wait(
  name=endpoint_name,
  config=EndpointCoreConfigInput(
    served_entities=[
      ServedEntityInput(
        entity_name=feature_spec_name,
        scale_to_zero_enabled=True,
        workload_size="Small"
      )
    ]
  )
)

fe.create_feature_serving_endpoint(
  name="user-preferences",
  config=EndpointCoreConfig(
    served_entities=ServedEntity(
      feature_spec_name="catalog.default.user_preferences_spec",
      workload_size="Small",
      scale_to_zero_enabled=True
    )
  )
)

Obtenha dados do endpoint de atendimento do recurso.

Para acessar o endpoint da API, envie uma solicitação HTTP GET para o URL do endpoint. O exemplo mostra como fazer isso usando as APIs do Python. Para outras linguagens e ferramentas, consulte Recurso Serving.

# Set up credentials
export DATABRICKS_TOKEN=...

url = "https://{workspace_url}/serving-endpoints/user-preferences/invocations"

headers = {'Authorization': f'Bearer {DATABRICKS_TOKEN}', 'Content-Type': 'application/json'}

data = {
  "dataframe_records": [{"user_id": user_id}]
}
data_json = json.dumps(data, allow_nan=True)

response = requests.request(method='POST', headers=headers, url=url, data=data_json)
if response.status_code != 200:
  raise Exception(f'Request failed with status {response.status_code}, {response.text}')

print(response.json()['outputs'][0]['hotel_preference'])

Use tabelas online com aplicativos RAG

Os aplicativos RAG são um caso de uso comum para tabelas online. Você cria uma tabela on-line para os dados estruturados que a aplicação RAG precisa e os hospeda em um endpoint que atende recursos. A aplicação RAG usa o endpoint de recurso para procurar dados relevantes na tabela online.

Os passos típicos são os seguintes:

Crie um endpoint de atendimento de recursos.
Crie uma ferramenta usando o LangChain ou qualquer pacote semelhante que use o endpoint para procurar dados relevantes.
Use a ferramenta em um agente LangChain ou em um agente semelhante para recuperar dados relevantes.
Crie um modelo de serviço endpoint para hospedar o aplicativo.

Para obter instruções passo a passo e um exemplo Notebook, consulte o exemplo de recurso engenharia: aplicativo RAG estruturado.

Exemplos Notebook

O Notebook a seguir ilustra como publicar recursos em tabelas online para veiculação em tempo real e pesquisa automatizada de recursos.

Notebookde demonstração de tabelas online

Abra o bloco de anotações em outra guia

Usar tabelas on-line com o Mosaic AI Model Serving

O senhor pode usar tabelas on-line para procurar o recurso para Mosaic AI Model Serving. Quando o senhor sincroniza uma tabela de recurso com uma tabela on-line, os modelos treinados usando recurso dessa tabela de recurso procuram automaticamente os valores de recurso da tabela on-line durante a inferência. Não é necessária nenhuma configuração adicional.

Use um FeatureLookup para ensinar o modelo.

Para treinamento de modelo, use recurso da tabela de recursos offline no conjunto de treinamento de modelo, conforme mostrado no exemplo a seguir:

training_set = fe.create_training_set(
  df=id_rt_feature_labels,
  label='quality',
  feature_lookups=[
      FeatureLookup(
          table_name="user_preferences",
          lookup_key="user_id"
      )
  ],
  exclude_columns=['user_id'],
)

Servir o modelo com o Mosaic AI Model Serving. O modelo procura automaticamente o recurso na tabela on-line. Para obter detalhes, consulte Pesquisa automática de recurso com Databricks servindo modelo.

Permissões de usuário

Você deve ter as seguintes permissões para criar uma tabela online:

SELECT privilégio na tabela de origem.
USE_CATALOG privilégio no catálogo de destino.
USE_SCHEMA e privilégio CREATE_TABLE no esquema de destino.

Para gerenciar o pipeline de sincronização de dados de uma tabela online, você deve ser o proprietário da tabela online ou receber o privilégio REFRESH na tabela online. Os usuários que não possuem privilégios USE_CATALOG e USE_SCHEMA no catálogo não verão a tabela on-line no Catalog Explorer.

O metastore Unity Catalog deve ter o Privilege Model Version 1.0.

Modelo de permissão de endpoint

Um principal de serviço de sistema exclusivo é criado automaticamente para um recurso que atende ou endpoint de modelo de operação com permissões limitadas necessárias para query dados e executar funções. Esta entidade de serviço permite que endpoint acesse dados e recursos funcionais independentemente do usuário que criou o recurso e garante que o endpoint possa continuar a funcionar se o criador deixar o workspace.

A vida útil deste sistema entidade de serviço é a vida útil do endpoint. Os logs de auditoria podem indicar registros gerados pelo sistema para o proprietário do catálogo do Unity Catalog, concedendo os privilégios necessários a essa entidade de serviço do sistema.

Limitações

Apenas uma tabela online é suportada por tabela de origem.
Uma tabela on-line e sua tabela de origem podem ter no máximo 1.000 colunas.
Colunas dos tipos de dados ARRAY, MAP ou STRUCT não podem ser usadas como key primária na tabela online.
Se uma coluna for usada como key primária na tabela online, todas as linhas na tabela de origem onde a coluna contém valores nulos serão ignoradas.
Tabelas externas, de sistema e internas não são suportadas como tabelas de origem.
As tabelas de origem sem o feed de dados de alteração Delta ativado suportam apenas o modo de sincronização Snapshot .
As tabelas Delta Sharing são suportadas apenas no modo de sincronização Snapshot .
Os nomes de catálogo, esquema e tabela da tabela online só podem conter caracteres alfanuméricos e sublinhado e não devem começar com números. Traços (-) não são permitidos.
Colunas do tipo strings são limitadas a 64 KB de comprimento.
Os nomes das colunas são limitados a 64 caracteres.
O tamanho máximo da linha é 2 MB.
O tamanho máximo de uma tabela online durante a visualização pública fechada é de 200 GB de dados do usuário não compactados.
O tamanho combinado de todas as tabelas online em um metastore Unity Catalog durante a visualização pública fechada é de 1 TB de dados do usuário não compactados.
O número máximo de consultas por segundo (QPS) é 200. Esse limite pode ser aumentado para 25.000 ou mais. Entre em contato com a equipe da Databricks account para aumentar o limite.

Solução de problemas

Não vejo a opção Criar tabela on-line

A causa geralmente é que a tabela da qual você está tentando sincronizar (a tabela de origem) não é um tipo compatível. Certifique-se de que o tipo protegido da tabela de origem (mostrado na Detalhes do Catalog tabExplorer) seja uma das opções suportadas abaixo:

TABLE_EXTERNAL
TABLE_DELTA
TABLE_DELTA_EXTERNAL
TABLE_DELTASHARING
TABLE_DELTASHARING_MUTABLE
TABLE_STREAMING_LIVE_TABLE
TABLE_STANDARD
TABLE_FEATURE_STORE
TABLE_FEATURE_STORE_EXTERNAL
TABLE_VIEW
TABLE_VIEW_DELTASHARING
TABLE_MATERIALIZED_VIEW

Não consigo selecionar os modos de sincronização Triggered ou Continuous quando crio uma tabela on-line

Isso acontece se a tabela de origem não tiver o feed de dados de alteração Delta ativado ou se for uma view ou view materializada. Para usar o modo de sincronização incremental , habilite o feed de dados alterados na tabela de origem ou use uma tabela semview .

A atualização da tabela on-line falha ou o status é exibido como off-line

Para começar a solucionar esse erro, clique no ID do pipeline que aparece na Visão geral tab da tabela on-line no Catalog Explorer.

Na página da interface do usuário do pipeline que aparece, clique na entrada que diz "Failed to resolve flow '__online_table".

mensagem de erro do pipeline de tabelas on-line

É exibida uma janela pop-up com detalhes na seção Error details (Detalhes do erro ).

As causas comuns de erros incluem o seguinte:

A tabela de origem foi excluída, ou excluída e recriada com o mesmo nome, enquanto a tabela on-line estava sendo sincronizada. Isso é particularmente comum em tabelas on-line contínuas, pois elas estão constantemente sincronizando.
A tabela de origem não pode ser acessada pelo site serverless compute devido às configurações de firewall. Nessa situação, a seção Detalhes do erro pode mostrar a mensagem de erro "Failed to begin the DLT service on clusters xxx..." (Falha ao iniciar o serviço DLT nos clusters xxx...).
O tamanho agregado das tabelas on-line excede o limite de 1 TiB (tamanho não compactado) em todo o metastore. O limite de 1 TiB refere-se ao tamanho não compactado após a expansão da tabela Delta em formato orientado por linha. O tamanho da tabela no formato de linha pode ser significativamente maior do que o tamanho da tabela Delta mostrada no Catalog Explorer, que se refere ao tamanho compactado da tabela em um formato orientado por coluna. A diferença pode ser de até 100x, dependendo do conteúdo da tabela.

Para estimar o tamanho não compactado e expandido por linha de uma tabela Delta, use a seguinte consulta de um site serverless SQL warehouse. A consulta retorna o tamanho estimado da tabela expandida em bytes. A execução bem-sucedida dessa consulta também confirma que o site serverless compute pode acessar a tabela de origem.
```
SELECT sum(length(to_csv(struct(*)))) FROM `source_table`;
```