Partilhar via

Use tabelas online para serviço de funcionalidades 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 online são projetadas para funcionar com os aplicativos Mosaic AI Model Serving, Feature Serving e geração aumentada por recuperação (RAG), onde são usadas para consultas rápidas de dados.

Você pode também usar tabelas online em consultas usando 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

Você cria 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 utilizar para a tabela em linha 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 Descrição
    Instantâneo O pipeline é executado uma vez para capturar 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, capturando um novo instantâneo da tabela de origem e criar uma nova cópia. O conteúdo da tabela online é atualizado atomicamente.
    Acionado O pipeline é executado uma vez para criar um instantâneo inicial da tabela de origem na tabela online. Ao contrário do modo de sincronização por 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 de alterações ativado.

  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.

Obtenha relatórios de status e ative atualizações usando a interface do utilizador

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 aba 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 de DLT 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 em Modo de Sincronização Desencadeado, pode agendar atualizações periódicas automáticas. O agendamento de atualização é gerenciado pelo pipeline DLT 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 Eliminar no menu de 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.

Utilize o ID do pipeline associado à tabela online na especificação da tabela online e inicie uma nova atualização no pipeline para desencadear 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 '
            'DLT: '
            '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 DLT: 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 endpoint de serviço de funcionalidades

Para modelos e aplicações hospedados fora do Databricks, pode-se criar um ponto de extremidade para servir funcionalidades 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 consultas online, o ponto de acesso de serviço usa automaticamente a tabela online para executar consultas de funcionalidades 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. Criar um ponto de extremidade para disponibilização de funcionalidades.

    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 de recurso para criar um ponto de extremidade para disponibilização de recursos. O endpoint disponibiliza dados através 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 endpoint de disponibilização de funcionalidades.

    Para acessar o ponto de extremidade da API, envie uma solicitação de GET HTTP 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 a aplicação RAG precisa e hospeda-a em um endpoint de serviço de funcionalidades. A aplicação RAG utiliza o ponto de extremidade para acessar funcionalidades e procurar dados relevantes da tabela online.

As etapas típicas são as seguintes:

  1. Crie um endpoint de serviço de característica.
  2. Crie uma ferramenta usando LangChain ou qualquer pacote semelhante que utilize o endpoint para buscar 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 cadernos

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.

Notebook de demonstração de tabelas online

Obter caderno

Utilize tabelas online com o Mosaic AI Model Serving

Você pode usar tabelas on-line para procurar recursos para o Mosaic AI Model Serving. Quando sincronizas uma tabela de características com uma tabela online, os modelos treinados usando características dessa tabela procuram automaticamente os valores das características 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. Utilize o serviço Mosaic AI Model Serving para servir o modelo. O modelo procura automaticamente as características 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 privilégio na tabela de origem.
  • USE_CATALOG privilégio no catálogo de destino.
  • USE_SCHEMA e CREATE_TABLE privilégios 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 de 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 Privilege Model Versão 1.0.

Modelo de permissão de endpoint

Uma entidade de serviço exclusiva é criada automaticamente para um ponto de acesso de entrega de funcionalidades ou entrega de modelos com permissões limitadas que permitem aceder a dados de tabelas online. Este principal de serviço permite que o ponto de extremidade aceda aos dados de forma independente do criador do recurso e garante que o ponto de extremidade possa continuar a funcionar caso o criador deixe o 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 cada 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 o feed de dados de alteração Delta ativado suportam apenas o modo de sincronização Instantâneo.
  • As tabelas do Delta Sharing são suportadas apenas no modo de sincronização de Snapshot.
  • 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 do pipeline online de tabelas

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 eliminada, ou eliminada e recriada com o mesmo nome, enquanto a tabela online estava a sincronizar. 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. Nesta situação, a secção Detalhes do Erro poderá 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 com linhas expandidas de uma tabela Delta, use a seguinte consulta num Warehouse SQL 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`;