CREATE TABLE [USING]

Artigo
11/14/2024

Aplica-se a: marca de seleção positiva SQL do Databricks 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 ou especificação de opções. 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:
  - Funções de agregação
  - Funções de janela analíticas
  - Classificação de funções de janela
  - Funções geradoras com valor de tabela
  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: SQL do Databricks 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: SQL do Databricks 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:
  - Funções de agregação
  - Funções de janela analíticas
  - Classificação de funções de janela
  - Funções geradoras com valor de tabela
  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: SQL do Databricks Databricks Runtime 12.2 LTS e versões posteriores 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

data_source pode ser um formato de arquivo ou uma fonte de dados JDBC federada.

O formato do arquivo deve ser um dos seguintes:
- AVRO
- BINARYFILE
- CSV
- DELTA
- JSON
- ORC
- PARQUET
- TEXT
Para qualquer formato de arquivo diferente DELTA , você também deve especificar a LOCATION , a menos que o catálogo de tabelas seja hive_metastore.

As seguintes origens JDBC federadas são suportadas:
- POSTGRESQL
- SQLSERVER
- MYSQL
- BIGQUERY
- NETSUITE
- ORACLE
- REDSHIFT
- SNOWFLAKE
- SQLDW
- SYNAPSE
- SALESFORCE
- SALESFORCE_DATA_CLOUD
- TERADATA
- WORKDAY_RAAS
- MONGODB
Ao especificar uma origem JDBC federada, você também deve especificar a OPTIONS cláusula com as informações de conexão necessárias. Consulte Consultar bancos de dados usando JDBC para obter mais informações sobre como consultar origens de dados federadas.

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.

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: Databricks SQL 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: SQL do Databricks Databricks Runtime 12.2 LTS e versões posteriores 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));

-- Create an external table connected to Oracle
> CREATE TABLE IF NOT EXISTS ora_tab
  USING ORACLE
  OPTIONS (
    url '<jdbc-url>',
    dbtable '<table-name>',
    user '<username>',
    password '<password>'
);

> SELECT * FROM ora_tab;

Compartilhar via

CREATE TABLE [USING]

Sintaxe

Parâmetros

Exemplos

Comentários

Recursos adicionais

Compartilhar via

CREATE TABLE [USING]

Sintaxe

Parâmetros

Exemplos

Artigos relacionados

Comentários

Recursos adicionais