CREATE TABLE [USING]

  • Artigo

Aplica-se a: marca de seleção positiva SQL do Databricks marca de seleção positiva Databricks Runtime

Define uma tabela externa ou gerenciada, opcionalmente usando uma fonte de dados.

Sintaxe

{ { [CREATE OR] REPLACE TABLE | CREATE [EXTERNAL] TABLE [ IF NOT EXISTS ] }
  table_name
  [ table_specification ]
  [ USING data_source ]
  [ table_clauses ]
  [ AS query ] }

table_specification
  ( { column_identifier column_type [ column_properties ] } [, ...]
    [ , table_constraint ] [...] )

column_properties
  { NOT NULL |
    GENERATED ALWAYS AS ( expr ) |
    GENERATED { ALWAYS | BY DEFAULT } AS IDENTITY [ ( [ START WITH start ] [ INCREMENT BY step ] ) ] |
    DEFAULT default_expression |
    COMMENT column_comment |
    column_constraint |
    MASK clause } [ ... ]

table_clauses
  { OPTIONS clause |
    PARTITIONED BY clause |
    CLUSTER BY clause |
    clustered_by_clause |
    LOCATION path [ WITH ( CREDENTIAL credential_name ) ] |
    COMMENT table_comment |
    TBLPROPERTIES clause |
    WITH { ROW FILTER clause } } [...]

clustered_by_clause
  { CLUSTERED BY ( cluster_column [, ...] )
    [ SORTED BY ( { sort_column [ ASC | DESC ] } [, ...] ) ]
    INTO num_buckets BUCKETS }

Parâmetros

  • REPLACE

    Se especificado, substitui a tabela e seu conteúdo, caso já exista. Só há suporte para essa cláusula em tabelas do Delta Lake.

    REPLACE preserva o histórico da tabela.

    Observação

    O Azure Databricks recomenda fortemente usar REPLACE em vez de remover e recriar tabelas do Delta Lake.

  • EXTERNAL

    Se especificado, cria uma tabela externa. Ao criar uma tabela externa, você também deve fornecer uma cláusula LOCATION. Quando uma tabela externa é descartada, os arquivos no LOCATION não serão removidos.

  • IF NOT EXISTS

    Se estiver especificado e uma tabela com o mesmo nome já existir, a instrução será ignorada.

    IF NOT EXISTS não pode coexistir com REPLACE, o que significa que CREATE OR REPLACE TABLE IF NOT EXISTS não é permitido.

  • table_name

    O nome da tabela a ser criada. O nome não deve incluir uma especificação temporal. Se o nome não for qualificado, a tabela será criada no esquema atual.

    Tabelas criadas em hive_metastore só podem conter caracteres alfanuméricos ASCII e sublinhados (INVALID_SCHEMA_OR_RELATION_NAME).

  • table_specification

    Esta cláusula opcional define a lista de colunas e os tipos, as propriedades, as descrições e as restrições de coluna associados.

    Se você não definir colunas, o esquema da tabela deverá especificar AS query ou LOCATION.

    • column_identifier

      Um nome exclusivo para a coluna.

      Os identificadores de coluna das tabelas Delta Lake sem propriedade de mapeamento de coluna ('delta.columnMapping.mode' = 'name') não devem conter os seguintes caracteres: , ; { } ( ) \n \t =.

      Os identificadores de coluna da tabela AVRO devem começar com um sublinhado (_) ou uma letra Unicode (incluindo letras não-ASCII), seguidos por uma combinação de letras e dígitos Unicode e sublinhados.

    • column_type

      Especifica o tipo dos dados da coluna. Nem todos os tipos de dados com suporte pelo Azure Databricks têm suporte de todas as fontes de dados.

    • NOT NULL

      Se especificado, a coluna não aceitará valores NULL. Só há suporte para essa cláusula em tabelas do Delta Lake.

    • GENERATED ALWAYS AS ( expr )

      Quando você especifica essa cláusula, o valor dessa coluna é determinado pelo expr especificado.

      expr pode ser composto por literais, identificadores de coluna dentro da tabela e funções ou operadores determinísticos e internos do SQL, exceto:

      Além disso, expr não deve conter nenhuma subconsulta.

    • GENERATED { ALWAYS | BY DEFAULT } AS IDENTITY [ ( [ START WITH start ] [ INCREMENT BY step ] ) ]

      Aplica-se a: verificação marcada como sim SQL do Databricks marca de seleção positiva Databricks Runtime 10.4 LTS e versões posteriores

      Define uma coluna de identidade. Quando você grava na tabela e não fornece valores para a coluna de identidade, ele será atribuído automaticamente a um valor que seja exclusivo e aumente (ou diminua, se step for negativo) estatisticamente. Só há suporte para essa cláusula em tabelas do Delta Lake. Essa cláusula só pode ser usada para colunas com tipo de dados BIGINT.

      Os valores atribuídos automaticamente começam com start e são incrementados por step. Os valores atribuídos são exclusivos, mas não têm garantia de serem contíguos. Ambos os parâmetros são opcionais e o valor padrão é 1. step não pode ser 0.

      Se os valores atribuídos automaticamente estiverem além do intervalo do tipo de coluna de identidade, a consulta falhará.

      Quando ALWAYS for usado, você não pode fornecer seus próprios valores para a coluna de identidade.

      Não há suporte para as operações a seguir:

      • PARTITIONED BY uma coluna de identidade
      • UPDATE uma coluna de identidade

      Observação

      Declarar uma coluna de identidade em uma tabela Delta desabilita transações simultâneas. Use apenas colunas de identidade em casos de uso em que as gravações simultâneas na tabela de destino não são necessárias.

    • DEFAULT default_expression

      Aplica-se a:verificação marcada como sim SQL do Databricks marca de seleção positiva Databricks Runtime 11.3 LTS e versões posteriores

      Define um valor DEFAULT para a coluna que é usada em INSERT, UPDATE e MERGE ... INSERT quando a coluna não é especificada.

      Se nenhum padrão for especificado, DEFAULT NULL será aplicado em colunas anuláveis.

      default_expression pode ser composto de literais e funções incorporadas de SQL ou operadores exceto:

      Além disso, default_expression não deve conter nenhuma subconsulta.

      DEFAULT há suporte para as fontes CSV, JSON, PARQUET e ORC.

    • COMMENT column_comment

      Um literal de cadeia de caracteres para descrever a coluna.

    • column_constraint

      Adiciona uma restrição de chave estrangeira ou chave primária à coluna em uma tabela do Delta Lake.

      As restrições não têm suporte para tabelas no catálogo hive_metastore.

      Para adicionar uma restrição de verificação a uma tabela do Delta Lake, use ALTER TABLE.

    • Cláusula MASK

      Aplica-se a: verificação marcada como sim SQL do Databricksverificação marcada como sim Databricks Runtime 12.2 LTS e versões posteriores marca de seleção positiva Somente Catálogo do Unity

      Importante

      Esse recurso está em uma versão prévia.

      Adiciona uma função de máscara de coluna para anonimizar dados confidenciais. Todas as consultas subsequentes dessa coluna recebem o resultado da avaliação dessa função sobre a coluna no lugar do valor original. Isso pode ser útil para fins de um controle de acesso detalhado, em que a função pode inspecionar a identidade e/ou as filiações a grupos do usuário que a invocou para decidir se quer ocultar o valor.

    • table_constraint

      Adiciona restrições de chave estrangeira informativa ou chave primária informativa à tabela do Delta Lake.

      As restrições de chave não têm suporte para tabelas no catálogo hive_metastore.

      Para adicionar uma restrição de verificação a uma tabela do Delta Lake, use ALTER TABLE.

  • USING data_source

    O formato de arquivo a ser usado para a tabela. data_source deve ser um destes:

    • AVRO
    • BINARYFILE
    • CSV
    • DELTA
    • JSON
    • ORC
    • PARQUET
    • TEXT

    Os seguintes formatos de arquivo adicionais a serem usados para a tabela têm suporte no Databricks Runtime:

    • JDBC
    • LIBSVM
    • O nome de classe totalmente qualificado de uma implementação de org.apache.spark.sql.sources.DataSourceRegister personalizada.

    Se USING for omitido, o padrão será DELTA.

    Para qualquer data_source diferente de DELTA, você também deve especificar um LOCATION a menos que o catálogo de tabelas seja hive_metastore.

    O seguinte se aplica ao: Databricks Runtime

    HIVE tem suporte para criar uma tabela SerDe do Hive no Databricks Runtime. Você pode especificar file_format e row_format específicos do Hive usando a cláusula OPTIONS, que é um mapa de cadeia de caracteres que não diferencia maiúsculas e minúsculas. Os option_keys são:

    • FILEFORMAT
    • INPUTFORMAT
    • OUTPUTFORMAT
    • SERDE
    • FIELDDELIM
    • ESCAPEDELIM
    • MAPKEYDELIM
    • LINEDELIM

  • table_clauses

    Opcionalmente, especifique o local, o particionamento, o clustering, as opções, os comentários e as propriedades definidas pelo usuário para a nova tabela. Cada subcláusula só pode ser especificada uma vez.

    • PARTITIONED BY

      Uma cláusula opcional para particionar a tabela por um subconjunto de colunas.

      Observação

      Se você não definir uma tabela Delta, as colunas de particionamento serão colocadas no final da tabela, mesmo que tenham sido definidas anteriormente na especificação da coluna. Considere usar CLUSTER BY em vez de PARTITIONED BY para tabelas Delta.

    • CLUSTER POR

      Aplica-se a: verificação marcada como sim Databricks SQL verificação marcada como sim Databricks Runtime 13.3 e posterior

      Uma cláusula opcional para agrupar uma tabela Delta por um subconjunto de colunas. Para agrupar outras tabelas use clustered_by_clause.

      O clustering líquido do Delta Lake não pode ser combinado com PARTITIONED BY.

    • clustered_by_clause

      Opcionalmente, agrupe a tabela ou cada partição num número fixo de buckets de hash através de um subconjunto das colunas.

      Não há suporte para clustering para tabelas do Delta Lake.

      • CLUSTERED BY

        Especifica o conjunto de colunas pelo qual agrupar cada partição ou a tabela se nenhum particionamento for especificado.

        • cluster_column

          Um identificador que faz referência a um column_identifier na tabela. Se você especificar mais de uma coluna, não poderá haver colunas duplicadas. Como um cluster funciona no nível de partição, você não deve nomear uma coluna de partição também como uma coluna de cluster.

      • SORTED BY

        Mantém opcionalmente uma ordem de classificação para linhas em um bucket.

        • sort_column

          Uma coluna pela qual classificar o bucket. A coluna não deve ser uma coluna de partição. As colunas de classificação devem ser exclusivas.

        • ASC ou DESC

          Opcionalmente, especifica se o sort_column está classificado em ordem crescente (ASC) ou decrescente (DESC). Os valores padrão são ASC.

      • INTO num_buckets BUCKETS

        Um inteiro literal que especifica o número de buckets nos quais cada partição (ou a tabela caso nenhum particionamento seja especificado) é dividida.

    • Caminho de LOCATION [ WITH ( CREDENTIAL credential_name ) ]

      Um caminho opcional para o diretório onde os dados da tabela estão armazenados, que pode ser um caminho no armazenamento distribuído. path deve ser uma literal STRING. Se você não especificar nenhum local, a tabela será considerada uma managed table e o Azure Databricks criará um local de tabela padrão.

      A especificação de um local torna a tabela uma tabela externa.

      No caso das tabelas que não estão no catálogo hive_metastore, a tabela path deve ser protegida por um local externo, a menos que uma credencial de armazenamento válida seja especificada.

      Não é possível criar tabelas externas em locais que se sobreponham ao local das tabelas gerenciadas.

      Para uma tabela do Delta Lake, a configuração da tabela é herdada da LOCATION se os dados estiverem presentes. Portanto, se uma das cláusulas TBLPROPERTIES, table_specification ou PARTITIONED BY for especificada para tabelas do Delta Lake, ela deverá corresponder exatamente aos dados de localização do Delta Lake.

    • OPÇÕES

      Configura ou reconfigura uma ou mais opções de tabela definidas pelo usuário.

    • COMMENT table_comment

      Um literal de cadeia de caracteres para descrever a tabela.

    • TBLPROPERTIES

      Opcionalmente, define uma ou mais propriedades definidas pelo usuário.

    • Cláusula WITH ROW FILTER

      Aplica-se a: verificação marcada como sim SQL do Databricksverificação marcada como sim Databricks Runtime 12.2 LTS e versões posteriores verificação marcada como sim Somente Catálogo do Unity

      Adiciona uma função de filtro de linha à tabela. Todas as consultas subsequentes dessa tabela receberão um subconjunto das linhas onde a função avalia como o valor booliano TRUE. Isso pode ser útil para fins de controle de acesso refinado, em que a função pode inspecionar a identidade ou as associações de grupo do usuário que a invocou para decidir se deseja filtrar algumas linhas.

  • AS query

    Essa cláusula opcional preenche a tabela usando os dados de query. Ao especificar um query, você não deve especificar um table_specification também. O esquema da tabela é derivado da consulta.

    Observe que o Azure Databricks substitui a fonte de dados subjacente pelos dados da consulta de entrada, para garantir que a tabela criada contenha exatamente os mesmos dados que a consulta de entrada.

Exemplos

-- Creates a Delta table
> CREATE TABLE student (id INT, name STRING, age INT);

-- Use data from another table
> CREATE TABLE student_copy AS SELECT * FROM student;

-- Creates a CSV table from an external directory
> CREATE TABLE student USING CSV LOCATION '/path/to/csv_files';

-- Specify table comment and properties
> CREATE TABLE student (id INT, name STRING, age INT)
    COMMENT 'this is a comment'
    TBLPROPERTIES ('foo'='bar');

-- Specify table comment and properties with different clauses order
> CREATE TABLE student (id INT, name STRING, age INT)
    TBLPROPERTIES ('foo'='bar')
    COMMENT 'this is a comment';

-- Create partitioned table
> CREATE TABLE student (id INT, name STRING, age INT)
    PARTITIONED BY (age);

-- Create a table with a generated column
> CREATE TABLE rectangles(a INT, b INT,
                          area INT GENERATED ALWAYS AS (a * b));