Partilhar via

Use tabelas on-line para veiculação de recursos em tempo real

  • Artigo

Importante

As tabelas online estão em Pré-visualização Pública nas seguintes regiões: westus, eastus, eastus2, northeurope, westeurope. Para obter informações sobre preços, consulte Preços de tabelas online.

Uma tabela online é uma cópia somente leitura de uma tabela delta armazenada em formato orientado a linha otimizado para acesso online. As tabelas online são tabelas totalmente sem servidor que dimensionam automaticamente a capacidade de taxa de transferência com a carga de solicitação e fornecem acesso de baixa latência e alta taxa de transferência a dados de qualquer escala. As tabelas on-line são projetadas para funcionar com aplicativos Mosaic AI Model Serving, Feature Serving e geração aumentada de recuperação (RAG), onde são usadas para pesquisas rápidas de dados.

Você também pode usar tabelas online em consultas usando a Lakehouse Federation. Ao usar o Lakehouse Federation, você deve usar um armazém SQL sem servidor para acessar tabelas online. Somente operações de leitura (SELECT) são suportadas. Esse recurso destina-se apenas para 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.

Criar uma tabela online 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. Você também pode usar a API REST ou o SDK do Databricks para criar e gerenciar tabelas online. Consulte Trabalhar com tabelas online usando APIs.

Requisitos

  • O espaço de trabalho deve estar habilitado para o Catálogo Unity. Siga a documentação para criar um Unity Catalog Metastore, habilitá-lo em um espaço de trabalho e criar um catálogo.
  • Um modelo deve ser registrado no Catálogo Unity para acessar tabelas online.

Trabalhar com tabelas online 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 online usando a interface do usuário

Criar uma tabela online usando o Catalog Explorer. Para obter informações sobre as permissões necessárias, consulte Permissões de usuário.

  1. Para criar uma tabela online, a tabela Delta de origem deve ter uma chave primária. Se a tabela Delta que você deseja usar não tiver uma chave primária, crie uma seguindo estas instruções: Use uma tabela Delta existente no Unity Catalog como uma tabela de recursos.

  2. No Gerenciador de Catálogos, navegue até a tabela de origem que você deseja sincronizar com uma tabela online. No menu Criar, selecione Tabela online.

    Selecione Criar tabela online

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

    Caixa de diálogo Configurar tabela online

    Nome: Nome a ser usado para a tabela online no Catálogo Unity.

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

    Chave de série temporal: (Opcional). Coluna na tabela de origem para usar como chave de série temporal. Quando especificado, a tabela online inclui apenas a linha com o valor de chave de série temporal mais recente para cada chave primária.

    Modo de sincronização: especifica como o pipeline de sincronização atualiza a tabela online. Selecione uma das opções Instantâneo, Acionado ou Contínuo.

    Política Description
    Snapshot O pipeline é executado uma vez para tirar um instantâneo 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 online, tirando um novo instantâneo da fonte e criando uma nova cópia. O conteúdo da tabela online é atualizado atomicamente.
    Acionado O pipeline é executado uma vez para criar uma cópia de instantâneo inicial da tabela de origem na tabela online. Ao contrário do modo de sincronização de instantâneo, quando a tabela online é atualizada, apenas as alterações desde a última execução do pipeline são recuperadas e aplicadas à tabela online. A atualização incremental pode ser acionada manualmente ou automaticamente de acordo com uma programação.
    Contínuo O gasoduto funciona continuamente. As alterações subsequentes à tabela de origem são aplicadas incrementalmente à tabela online no modo de streaming em tempo real. Nenhuma atualização manual é necessária.

Nota

Para oferecer suporte ao modo de sincronização acionada ou contínua , a tabela de origem deve ter o feed de dados Change habilitado .

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

Obter atualizações de status e disparar 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 guia Visão geral aberta. A seção Ingestão de dados 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.

vista da página da tabela online no catálogo

Agendar atualizações periódicas

Para tabelas online com instantâneo ou modo de sincronização acionado, você pode agendar atualizações periódicas automáticas. O agendamento de atualização é gerenciado pelo pipeline Delta Live Tables que atualiza a tabela.

  1. No Gerenciador de Catálogos, navegue até a tabela online.
  2. Na seção Ingestão de dados, clique no link para o pipeline.
  3. No canto superior direito, clique em Agendar e adicione uma nova agenda ou atualize agendas existentes.

Excluir uma tabela online usando a interface do usuário

Na página da tabela online, selecione Excluir no Menu de kebab menu kebab.

Trabalhar com tabelas online usando APIs

Você também pode usar o SDK do Databricks ou a API REST para criar e gerenciar tabelas online.

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

Requisitos

Databricks SDK versão 0.20 ou superior.

Criar uma tabela online usando APIs

Databricks SDK - Python

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'})
)

online_table = OnlineTable(
  name="main.default.my_online_table",  # Fully qualified table name
  spec=spec  # Online table specification
)

w.online_tables.create_and_wait(table=online_table)

API REST

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 online começa a ser sincronizada automaticamente após a sua criação.

Obter status e acionar a atualização usando APIs

Você pode visualizar o status e as especificações da tabela on-line seguindo o exemplo abaixo. Se sua tabela online não for contínua e você quiser acionar uma atualização manual de seus dados, poderá usar a API de pipeline para fazer isso.

Use o ID do pipeline associado à tabela online na especificação da tabela online e inicie uma nova atualização no pipeline para acionar a atualização. Isso equivale a clicar em Sincronizar agora na interface do usuário da tabela online no Gerenciador de Catálogos.

Databricks SDK - Python

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)

API REST

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 online usando APIs

Databricks SDK - Python

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

API REST

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 online interrompe qualquer sincronização de dados em andamento e libera todos os seus recursos.

Servir dados de tabela online usando um ponto de extremidade de serviço de recurso

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

  1. 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 online, o ponto de extremidade de serviço usa automaticamente a tabela online para executar pesquisas de recursos de baixa latência.

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

    A especificação do recurso pode ser visualizada na guia Função no Gerenciador de Catálogos.

    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"
    )
  ]
)

  2. Crie um ponto de extremidade de serviço de recurso.

    Esta etapa pressupõe que você tenha criado uma tabela online chamada user_preferences_online_table que sincroniza dados da tabela user_preferencesDelta . Use a especificação do recurso para criar um ponto de extremidade de serviço de recurso. O ponto de extremidade disponibiliza dados por meio de uma API REST usando a tabela online associada.

    Nota

    O usuário que executa essa operação deve ser o proprietário da tabela offline e da tabela online.

    Databricks SDK - Python

    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"
      )
    ]
  )
)

    API Python

    from databricks.feature_engineering.entities.feature_serving_endpoint import (
  ServedEntity,
  EndpointCoreConfig,
)

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
    )
  )
)

  3. Obtenha dados do ponto de extremidade de serviço do recurso.

    Para acessar o ponto de extremidade da API, envie uma solicitação HTTP GET para a URL do ponto de extremidade. O exemplo mostra como fazer isso usando APIs Python. Para outros idiomas e ferramentas, consulte Feature 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 on-line com aplicativos RAG

As aplicações RAG são um caso de uso comum para tabelas online. Você cria uma tabela online para os dados estruturados de que o aplicativo RAG precisa e hospeda-a em um ponto de extremidade de serviço de recurso. O aplicativo RAG usa o recurso que serve o ponto de extremidade para procurar dados relevantes da tabela online.

As etapas típicas são as seguintes:

  1. Crie um ponto de extremidade de serviço de recurso.
  2. Crie uma ferramenta usando LangChain ou qualquer pacote semelhante que use o ponto de extremidade para procurar dados relevantes.
  3. Use a ferramenta em um agente LangChain ou agente semelhante para recuperar dados relevantes.
  4. Crie um modelo de ponto de extremidade de serviço para hospedar o aplicativo.

Para obter instruções passo a passo e um exemplo de bloco de anotações, consulte Exemplo de engenharia de recursos: aplicativo RAG estruturado.

Exemplos de blocos de notas

O bloco de anotações a seguir ilustra como publicar recursos em tabelas online para serviço em tempo real e pesquisa automatizada de recursos.

Caderno de demonstração de mesas online

Obter o bloco de notas

Use mesas on-line com o Mosaic AI Model Serving

Você pode usar tabelas on-line para procurar recursos para o Mosaic AI Model Serving. Quando você sincroniza uma tabela de recursos com uma tabela online, os modelos treinados usando recursos dessa tabela de recursos pesquisam automaticamente os valores de feição da tabela online durante a inferência. Não é necessária qualquer configuração adicional.

  1. Use a FeatureLookup para treinar o modelo.

    Para treinamento de modelo, use recursos 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'],
)

  2. Sirva o modelo com o Mosaic AI Model Serving. O modelo procura automaticamente as funcionalidades da tabela online. Consulte Pesquisa automática de recursos com o Databricks Model Serving para obter detalhes.

Permissões de usuário

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

  • SELECT na tabela de origem.
  • USE_CATALOG no catálogo de destino.
  • USE_SCHEMA e CREATE_TABLE privilégio 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 têm privilégios de USE_CATALOG e USE_SCHEMA no catálogo não verão a tabela online no Gerenciador de Catálogos.

O metastore do Unity Catalog deve ter o Privilege Model Versão 1.0.

Modelo de permissão de ponto de extremidade

Uma entidade de serviço exclusiva é criada automaticamente para um ponto de extremidade de serviço de recurso ou modelo de serviço com permissões limitadas necessárias para consultar dados de tabelas online. Essa entidade de serviço permite que os pontos de extremidade acessem dados independentemente do usuário que criou o recurso e garante que o ponto de extremidade possa continuar a funcionar se o criador sair do espaço de trabalho.

O tempo de vida dessa entidade de serviço é o tempo de vida do ponto de extremidade. Os logs de auditoria podem indicar registros gerados pelo sistema para o proprietário do catálogo Unity concedendo privilégios necessários a essa entidade de serviço.

Limitações

  • Apenas uma tabela online é suportada por tabela de origem.
  • Uma tabela online e sua tabela de origem podem ter no máximo 1000 colunas.
  • As colunas dos tipos de dados ARRAY, MAP ou STRUCT não podem ser usadas como chaves primárias na tabela online.
  • Se uma coluna for usada como chave primária na tabela online, todas as linhas da tabela de origem em que a coluna contém valores nulos serão ignoradas.
  • Não há suporte para tabelas estrangeiras, de sistema e internas como tabelas de origem.
  • As tabelas de origem sem feed de dados de alteração delta habilitado suportam apenas o modo de sincronização de instantâneo .
  • As tabelas de Partilha Delta só são suportadas no modo de sincronização de instantâneos .
  • Os nomes de catálogo, esquema e tabela da tabela online só podem conter caracteres alfanuméricos e sublinhados, e não devem começar com números. Traços (-) não são permitidos.
  • As colunas do tipo String são limitadas a 64KB de comprimento.
  • Os nomes das colunas são limitados a 64 caracteres.
  • O tamanho máximo da linha é de 2MB.
  • O tamanho combinado de todas as tabelas on-line em um metastore do Unity Catalog durante a visualização pública é de 2 TB de dados de usuário não compactados.
  • O máximo de consultas por segundo (QPS) é de 12.000. Entre em contato com sua equipe de conta Databricks para aumentar o limite.

Resolução de Problemas

Não vejo a opção Criar tabela online

A causa geralmente é que a tabela que você está tentando sincronizar (a tabela de origem) não é um tipo suportado. Verifique se o Tipo Protegível da tabela de origem (mostrado na guia Detalhes do Catalog Explorer) é 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 Acionado ou Contínuo quando crio uma tabela online

Isso acontece se a tabela de origem não tiver o feed de dados de alteração Delta habilitado ou se for uma exibição ou uma exibição materializada. Para usar o modo de sincronização incremental , habilite o feed de dados de alteração na tabela de origem ou use uma tabela que não seja de exibição.

A atualização da tabela online falha ou o status é exibido offline

Para começar a solucionar esse erro, clique na ID do pipeline que aparece na guia Visão geral da tabela online no Gerenciador de Catálogos.

Falha no pipeline de tabelas online

Na página da interface do usuário do pipeline exibida, clique na entrada que diz "Falha ao resolver o fluxo '__online_table".

Mensagem de erro de pipeline de tabelas online

Um pop-up aparece com detalhes na seção Detalhes do erro.

Tabelas online 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 online estava sincronizando. Isso é particularmente comum com mesas on-line contínuas, porque elas estão em constante sincronização.

  • A tabela de origem não pode ser acessada por meio do Serverless Compute devido às configurações do firewall. Nessa situação, a seção Detalhes do erro pode mostrar a mensagem de erro "Falha ao iniciar o serviço DLT no cluster xxx...".

  • O tamanho agregado das tabelas online excede o limite de 2 TB (tamanho não compactado) em todo o metastore. O limite de 2 TB refere-se ao tamanho descompactado após a expansão da tabela Delta no formato orientado a linhas. O tamanho da tabela em formato de linha pode ser significativamente maior do que o tamanho da tabela Delta mostrada no Gerenciador de Catálogos, que se refere ao tamanho compactado da tabela em um formato orientado a colunas. A diferença pode ser tão grande quanto 100x, dependendo do conteúdo da tabela.

    Para estimar o tamanho descompactado e expandido em linha de uma tabela Delta, use a seguinte consulta de um SQL Warehouse sem servidor. A consulta retorna o tamanho estimado da tabela expandida em bytes. A execução bem-sucedida dessa consulta também confirma que o Serverless Compute pode acessar a tabela de origem.

    SELECT sum(length(to_csv(struct(*)))) FROM `source_table`;