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>' ]
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;
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);
Google Cloud Storage
CREATE STAGE mystage
URL='gcs://load/files/'
STORAGE_INTEGRATION = my_storage_int
DIRECTORY = (ENABLE = TRUE);
Microsoft Azure
CREATE STAGE mystage
URL='azure://myaccount.blob.core.windows.net/load/files/'
STORAGE_INTEGRATION = my_storage_int
DIRECTORY = (ENABLE = TRUE);
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;
Recuperação de URLs de arquivo das tabelas de diretório¶
Consulte uma tabela de diretório:
SELECT * FROM DIRECTORY( @<stage_name> )
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>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 desnowflakecomputing.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);
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;
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';
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.