Gerenciamento de tabelas de diretório

Este tópico fornece instruções para criar e gerenciar estágios externos ou internos com tabelas de diretório.

Neste tópico:

Atualização automática dos metadados da tabela de diretório

Os metadados de uma tabela de diretório podem ser atualizados automaticamente usando o serviço de mensagens de eventos para seu serviço de armazenamento em nuvem.

A operação de atualização sincroniza os metadados com o último conjunto de arquivos associados no caminho e estágio externo, ou seja:

  • Novos arquivos no caminho são adicionados aos metadados da tabela.

  • As mudanças nos arquivos do caminho são atualizadas nos metadados da tabela.

  • Os arquivos que não estão mais no caminho são removidos dos metadados da tabela.

Para instruções para criação de estágios com tabelas de diretório atualizadas automaticamente, consulte Atualizações automáticas de metadados da tabela de diretório.

Nota

A atualização automática dos metadados não está disponível para tabelas de diretório em estágios internos que fazem referência ao armazenamento em nuvem externo. Para esses tipos de estágios, você precisa atualizar manualmente os metadados da tabela de diretório. Para instruções, consulte Atualização manual dos metadados da tabela de diretório (neste tópico).

Para registrar qualquer arquivo ausente, sugerimos seguir nossas práticas recomendadas para preparar seus arquivos de dados e executar periodicamente uma instrução ALTER STAGE … REFRESH. Para obter um desempenho satisfatório, também recomendamos que você use um prefixo de caminho seletivo com ALTER STAGE. Isso reduz o número de arquivos que precisam ser listados e verificados se já foram registrados (por exemplo, bucket_name/YYYY/MM/DD/ ou mesmo bucket_name/YYYY/MM/DD/HH/ dependendo de seu volume).

Atualização manual dos metadados da tabela de diretório

Esta seção fornece instruções para a criação de estágios (usando CREATE STAGE) que cobrem uma tabela de diretório para armazenar metadados sobre os arquivos preparados. As tabelas de diretório criadas usando as instruções requerem atualizações manuais de metadados.

Atualmente, as tabelas de diretório em estágios internos requerem atualizações manuais de metadados. Você também pode optar por incluir uma tabela de diretório em estágios externos e atualizar os metadados manualmente. Para obter mais informações sobre atualizações automáticas de metadados, consulte Atualização automática dos metadados da tabela de diretório (neste tópico).

Nota

A atualização manual de metadados em um estágio externo impede que qualquer operação de atualização automatizada ocorra ao mesmo tempo. As atualizações automatizadas serão retomadas após a conclusão da atualização manual.

A sintaxe para criar um estágio com uma tabela de diretório é quase idêntica à criação de um estágio padrão externo ou interno. Defina o parâmetro opcional DIRECTORY como TRUE.

Para a descrição completa da sintaxe e dos parâmetros, consulte CREATE STAGE.

Sintaxe

-- Internal stage
CREATE [ OR REPLACE ] [ TEMPORARY ] STAGE [ IF NOT EXISTS ] <internal_stage_name>
  [ DIRECTORY = ( { ENABLE = TRUE | FALSE } ) ]
  [ ENCRYPTION = (TYPE = 'SNOWFLAKE_FULL' | TYPE = 'SNOWFLAKE_SSE') ]
  [ FILE_FORMAT = ( { FORMAT_NAME = '<file_format_name>' | TYPE = { CSV | JSON | AVRO | ORC | PARQUET | XML } [ formatTypeOptions ] } ) ]
  [ COPY_OPTIONS = ( copyOptions ) ]
  [ COMMENT = '<string_literal>' ]

-- External stage
CREATE [ OR REPLACE ] [ TEMPORARY ] STAGE [ IF NOT EXISTS ] <external_stage_name>
      <cloud_storage_access_settings>
    [ DIRECTORY = ( { ENABLE = TRUE | FALSE } ) ]
    [ FILE_FORMAT = ( { FORMAT_NAME = '<file_format_name>' | TYPE = { CSV | JSON | AVRO | ORC | PARQUET | XML } [ formatTypeOptions ] } ) ]
    [ COPY_OPTIONS = ( copyOptions ) ]
    [ COMMENT = '<string_literal>' ]
Copy

Onde:

ENABLE = TRUE | FALSE

Especifica se deve ser adicionada uma tabela de diretório ao estágio. Quando o valor é TRUE, uma tabela de diretório é criada com o estágio.

Padrão: FALSE

[ ENCRYPTION = (TYPE = 'SNOWFLAKE_FULL' | TYPE = 'SNOWFLAKE_SSE') ]

Especifica o tipo de criptografia suportada para todos os arquivos armazenados no estágio.

TYPE = ...

Especifica o tipo de criptografia utilizado. Os valores possíveis são:

  • SNOWFLAKE_FULL: criptografia do lado do cliente. Os arquivos são criptografados por um cliente quando ele os carrega no estágio interno usando PUT.

  • SNOWFLAKE_SSE: criptografia do lado do servidor. Os arquivos são criptografados quando chegam ao estágio.

    Especifique a criptografia do lado do servidor se você planeja consultar URLs de arquivos pré-assinados para seus arquivos preparados.

    Quando os arquivos em uma estágio são criptografados do lado do cliente, os usuários não podem ler os arquivos preparados sem ter acesso à chave de criptografia.

    Para obter mais informações sobre os estágios internos nomeados apenas com criptografia do lado do servidor, consulte CREATE STAGE.

Padrão: SNOWFLAKE_FULL

Notas de uso

  • Depois de criar um estágio com uma tabela de diretório, você deve executar ALTER STAGE … REFRESH para atualizar manualmente os metadados da tabela de diretório.

Exemplos

Criar um estágio interno chamado mystage que inclua uma tabela de diretório. O estágio faz referência a um formato de arquivo chamado myformat:

CREATE STAGE mystage
  DIRECTORY = (ENABLE = TRUE)
  FILE_FORMAT = myformat;
Copy

Criar um estágio externo chamado mystage que inclua uma tabela de diretório. O estágio faz referência a um bucket ou contêiner chamado load com um caminho de files. O acesso seguro ao local de armazenamento em nuvem é fornecido por meio da integração de armazenamento my_storage_int:

Nota

O local de armazenamento no valor de URL deve terminar em uma barra (/).

Amazon S3

CREATE STAGE mystage
  URL='s3://load/files/'
  STORAGE_INTEGRATION = my_storage_int
  DIRECTORY = (ENABLE = TRUE);
Copy

Google Cloud Storage

CREATE STAGE mystage
  URL='gcs://load/files/'
  STORAGE_INTEGRATION = my_storage_int
  DIRECTORY = (ENABLE = TRUE);
Copy

Microsoft Azure

CREATE STAGE mystage
  URL='azure://myaccount.blob.core.windows.net/load/files/'
  STORAGE_INTEGRATION = my_storage_int
  DIRECTORY = (ENABLE = TRUE);
Copy

Tabelas de diretório de atualização manual

Atualize os metadados em uma tabela de diretório manualmente usando o comando ALTER STAGE.

Por exemplo:

ALTER STAGE mystage REFRESH;
Copy

Recuperação de URLs de arquivo das tabelas de diretório

Consulte uma tabela de diretório:

SELECT * FROM DIRECTORY( @<stage_name> )
Copy

Onde:

stage_name

Nome de um estágio que inclui uma tabela de diretório.

Para obter mais informações sobre SELECT como uma instrução e as outras cláusulas dentro da instrução, consulte Sintaxe de consulta.

Saída

A saída de uma consulta de tabela de diretório pode incluir as seguintes colunas:

Coluna

Tipo de dados

Descrição

RELATIVE_PATH

TEXT

Caminho para os arquivos a serem acessados usando o URL do arquivo.

SIZE

NUMBER

Tamanho do arquivo (em bytes).

LAST_MODIFIED

TIMESTAMP_LTZ

Carimbo de data/hora em que o arquivo foi atualizado pela última vez no estágio.

MD5

HEX

Soma de verificação MD5 para o arquivo.

ETAG

HEX

Cabeçalho ETag para o arquivo.

FILE_URL

TEXT

URL do arquivo hospedado no Snowflake para o arquivo.

O URL do arquivo tem o seguinte formato:

https://<account_identifier>/api/files/<db_name>.<schema_name>.<stage_name>/<relative_path>
Copy

Onde:

account_identifier

Nome do host da conta Snowflake para seu estágio. O nome do host começa com um localizador de conta (fornecido pelo Snowflake) e termina com o domínio Snowflake (snowflakecomputing.com):

account_locator.snowflakecomputing.com

Para obter mais detalhes, consulte Identificadores de conta.

Nota

Para contas Business Critical, um segmento privatelink é anexado ao URL logo antes de snowflakecomputing.com (privatelink.snowflakecomputing.com), mesmo se a conectividade privada ao serviço Snowflake são estiver habilitado para sua conta.

db_name

Nome do banco de dados que contém o estágio em que seus arquivos estão localizados.

schema_name

Nome do esquema que contém o estágio em que seus arquivos estão localizados.

stage_name

Nome do estágio em que seus arquivos estão localizados.

relative_path

Caminho para os arquivos a serem acessados usando o URL do arquivo.

Notas de uso

  • Se os arquivos baixados de um estágio interno estiverem corrompidos, verifique com o criador do estágio se ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE') está definido para o estágio.

Exemplos

Recupere todas as colunas de metadados em uma tabela de diretório para um estágio chamado mystage:

SELECT * FROM DIRECTORY(@mystage);
Copy

Retorne os valores da coluna FILE_URL da mesma tabela de diretório. Somente retorne os URLs de arquivo para arquivos com tamanho maior do que 100.000 bytes:

SELECT FILE_URL FROM DIRECTORY(@mystage) WHERE SIZE > 100000;
Copy

Retorne os valores da coluna FILE_URL da mesma tabela de diretório. Retorne somente os URLs de arquivo para arquivos com valores separados por vírgula:

SELECT FILE_URL FROM DIRECTORY(@mystage) WHERE RELATIVE_PATH ILIKE '%.csv';
Copy

Fluxos em tabelas de diretório

Fluxos padrão (ou seja, delta) em uma tabela de diretórios rastreiam arquivos que são adicionados ou descartados no local de armazenamento em nuvem referenciado. Para a sintaxe do comando SQL e exemplos, consulte CREATE STREAM.