CREATE TABLE [USANDO]

2025-06-25

Aplica-se a: seleção marcada sim Databricks SQL Databricks Runtime

Define uma tabela gerenciada ou externa, 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 |
    COLLATE collation_name |
    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 |
    DEFAULT COLLATION default_collation_name |
    WITH { ROW FILTER clause } } [...]

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

Antes do Databricks Runtime 16.1, START WITH deve preceder INCREMENT BY.

Parâmetros

SUBSTITUIR

Se especificado, substitui a tabela e seu conteúdo, se ela já existir. Esta cláusula só é suportada para tabelas Delta e Apache Iceberg.

REPLACE preserva o histórico da tabela bem como os privilégios concedidos.

Nota

O Azure Databricks recomenda vivamente utilizar REPLACE em vez de eliminar e recriar tabelas.
EXTERNO

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

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

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

O nome da tabela a ser criada. O nome não deve incluir uma especificação temporal ou uma especificação de opções. Se o nome não estiver qualificado, a tabela será criada no esquema atual.

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

As tabelas Iceberg devem ser criadas no Unity Catalog. A criação de tabelas Iceberg no hive_metastore não é suportada.
especificação_da_tabela

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

Se não definir colunas, deve especificar ou AS query ou LOCATION no esquema da tabela.
- column_identifier
  
  Um nome exclusivo para a coluna.
  
  Os identificadores de coluna de tabelas delta sem propriedade de mapeamento de coluna ('delta.columnMapping.mode' = 'name') não devem conter espaços ou os seguintes caracteres: , ; { } ( ) \n \t = .
  
  Os identificadores de coluna de AVRO tabelas devem começar com um sublinhado (_) ou uma letra Unicode (incluindo letras não-ASCII) e ser seguidos por uma combinação de letras Unicode, dígitos e sublinhados.
  
  Os identificadores de coluna das tabelas devem ser exclusivos, não distinguir maiúsculas de minúsculas e seguir as regras padrão de identificador SQL de ICEBERG. Evite usar espaços ou caracteres especiais, pois eles podem não ser suportados por todos os mecanismos de consulta.
- tipo_coluna
  
  Especifica o tipo de dados da coluna. Nem todos os tipos de dados suportados pelo Azure Databricks são suportados por todas as origens de dados.
- NÃO NULO
  
  Se especificado, a coluna não aceita NULL valores. Esta cláusula é suportada apenas para tabelas Delta e Iceberg.
- COLLATE collation_name
  
  Aplica-se a: Databricks SQL Databricks Runtime 16.1 e superior
  
  Opcionalmente, para STRINGcolumn_type, nomeia a ordenação a ser aplicada para operações de comparação e classificação nesta coluna. O agrupamento padrão é a tabela default_collation_name.
- GERADO SEMPRE COMO ( expr )
  
  Quando você especifica essa cláusula, o valor desta coluna é determinado pelo especificado expr.
  
  O DEFAULT COLLATION da tabela deve ser UTF8_BINARY.
  
  expr pode ser composto por literais, identificadores de coluna dentro da tabela e funções ou operadores SQL determinísticos internos, exceto:
  - Funções agregadas
  - Funções de janela analítica
  - Funções da janela de classificação
  - Funções geradoras de valores de tabela
  - Colunas com ordenação diferente de UTF8_BINARY
  Também expr não deve conter nenhuma subconsulta.
- GERADO { SEMPRE | POR PADRÃO } COMO IDENTIDADE [ ( [ COMEÇAR COM início ] [ INCREMENTAR POR passo ] ) ]
  
  Aplica-se a: Databricks SQL Databricks Runtime 10.4 LTS e versões superiores
  
  Define uma coluna de identidade. Quando você grava na tabela e não fornece valores para a coluna de identidade, será atribuído automaticamente a ela um valor exclusivo e estatisticamente crescente (ou decrescente se step for negativo). Esta cláusula só é suportada para tabelas Delta. Esta cláusula só pode ser usada para colunas com tipo de dados BIGINT.
  
  Os valores atribuídos automaticamente começam com start e aumentam em step. Os valores atribuídos são únicos, mas não é garantido que sejam 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 é usado, você não pode fornecer seus próprios valores para a coluna de identidade.
  
  As seguintes operações não são suportadas:
  - PARTITIONED BY uma coluna de identidade
  - UPDATE uma coluna de identidade
  Nota
  
  Declarar uma coluna de identidade em uma tabela desabilita transações simultâneas. Utilize colunas de identidade apenas em casos de uso em que não sejam necessárias gravações simultâneas na tabela de destino.
- PADRÃO default_expression
  
  Aplica-se a: Databricks SQL Databricks Runtime 11.3 LTS e acima
  
  Define um DEFAULT valor para a coluna que é usado em INSERT, UPDATEe MERGE ... INSERT quando a coluna não é especificada.
  
  Se nenhum padrão for especificado, DEFAULT NULL será aplicado para colunas anuláveis.
  
  default_expression pode ser composto de literais e funções ou operadores SQL internos, exceto:
  - Funções agregadas
  - Funções de janela analítica
  - Funções da janela de classificação
  - Funções geradoras de valores de tabela
  Também default_expression não deve conter nenhuma subconsulta.
  
  DEFAULT é suportado para CSV, JSON, PARQUETe ORC fontes.
- COMENTÁRIO column_comment
  
  Um literal de cadeia de caracteres para descrever a coluna.
- column_constraint
  
  Adiciona uma restrição de chave primária ou chave estrangeira à coluna de uma tabela.
  
  Não há suporte para restrições para tabelas no hive_metastore catálogo.
  
  Para adicionar uma restrição de verificação a uma tabela, use ALTER TABLE.
- Cláusula MASK
  
  Aplica-se a: Databricks SQL Databricks Runtime 12.2 LTS e superior Unity Catalog somente
  
  Importante
  
  Esta funcionalidade está em Pré-visualização Pública.
  
  Adiciona uma função de máscara de coluna para anonimizar dados sensíveis. Todas as consultas subsequentes dessa coluna recebem o resultado da avaliação dessa função sobre a coluna no lugar do valor original da coluna. Isso pode ser útil para fins de controle de acesso refinado, onde a função pode inspecionar a identidade ou as associações de grupo do usuário que invoca para decidir se deseja redigir o valor.
- restrição_de_tabela
  
  Adiciona uma chave primária informacional ou restrições de chave estrangeira informativa à tabela.
  
  Não há suporte para restrições de chave para tabelas no hive_metastore catálogo.
  
  Para adicionar uma restrição de verificação a uma tabela, use ALTER TABLE.
USANDO fonte_de_dados

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

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

As seguintes fontes 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 fonte 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 fontes de dados federadas.

Os seguintes formatos de arquivo adicionais a serem usados para a tabela são suportados no Databricks Runtime:
- JDBC
- LIBSVM
- Um nome de classe totalmente qualificado de uma implementação personalizada do org.apache.spark.sql.sources.DataSourceRegister.
Se USING for omitido, o padrão será DELTA.

O seguinte se aplica a: Databricks Runtime

HIVE é suportado para criar uma tabela Hive SerDe no Databricks Runtime. Você pode especificar o file_format e o row_format específicos ao Hive usando a cláusula OPTIONS, que é um mapa de cadeia de caracteres insensível a maiúsculas e minúsculas. Os option_keys são:
- FILEFORMAT
- INPUTFORMAT
- OUTPUTFORMAT
- SERDE
- FIELDDELIM
- ESCAPEDELIM
- MAPKEYDELIM
- LINEDELIM
cláusulas_da_tabela

Opcionalmente, especifique local, particionamento, clustering, opções, comentários e propriedades definidas pelo usuário para a nova tabela. Cada subcláusula só pode ser especificada uma vez.
- PARTICIONADO POR
  
  Uma cláusula opcional para particionar a tabela por um subconjunto de colunas.
  
  Nota
  
  Para tabelas Iceberg gerenciadas, o Azure Databricks não oferece suporte ao PARTITIONED BY. Em vez disso, use clustering líquido (CLUSTER BY) para otimizar o layout de dados. Para tabelas Delta, se você omitir a definição de tabela, o Azure Databricks colocará colunas de particionamento no final da tabela, mesmo que você as liste anteriormente na especificação da coluna.
- CLUSTER BY
  
  Aplica-se a: Databricks SQL Databricks Runtime 13.3 e posteriores
  
  Uma cláusula opcional para agrupar uma tabela Delta ou Iceberg por um subconjunto de colunas. Veja Utilizar clustering líquido para tabelas. Para agrupar outras tabelas, use clustered_by_clause.
  
  Para tabelas Iceberg, deve-se desabilitar explicitamente vetores de exclusão e IDs de linha ao usar CLUSTER BY.
Não é possível combinar aglomeração líquida com PARTITIONED BY.
- cláusula_agrupada_por
  
  Opcionalmente, agrupe a tabela ou cada partição em um número fixo de hash buckets usando um subconjunto das colunas.
  
  Esta cláusula não é suportada para tabelas Delta ou Iceberg. Utilize CLUSTER BY em substituição.
  - AGRUPADOS POR
    
    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 na column_identifier tabela. Se você especificar mais de uma coluna, não deve haver duplicatas. Como um clustering opera no nível de partição, você não deve nomear uma coluna de partição também como uma coluna de cluster.
  - ORDENADO POR
    
    Opcionalmente, mantém uma ordem de classificação para linhas em um bucket.
    - sort_column
      
      Uma coluna para classificar o bucket. A coluna não deve ser usada como coluna de partição. As colunas de classificação devem ser exclusivas.
    - ASC ou DESC
      
      Opcionalmente, especifica se sort_column é classificado em ordem crescente (ASC) ou decrescente (DESC). Os valores padrão são ASC.
  - EM DIVISÕES DE num_buckets PARTIÇÕES
    
    Um literal INTEGER especificando o número de buckets em que cada partição (ou a tabela, se nenhum particionamento for especificado) é dividida.
- CAMINHO DA LOCALIZAÇÃO [ COM ( CREDENCIAL credential_name ) ]
  
  Um caminho opcional para o diretório onde os dados da tabela são armazenados, que pode ser um caminho no armazenamento distribuído. path deve ser um literal de cadeia de caracteres. Se você não especificar nenhum local, a tabela será considerada um 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.
  
  Para tabelas que não residem no hive_metastore catálogo, 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 sobrepõem ao local de tabelas gerenciadas.
  
  Para tabelas Delta, a tabela herda sua configuração do LOCATION se os dados já existirem nesse caminho. Como resultado, quaisquer cláusulas especificadas TBLPROPERTIES, table_specification ou PARTITIONED BY devem corresponder exatamente aos dados existentes no local Delta.
  
  Para tabelas Iceberg, a cláusula LOCATION não é suportada. As tabelas Iceberg estrangeiras são registradas automaticamente quando você cria um catálogo estrangeiro e você deve criar tabelas Iceberg gerenciadas sem especificar um local.
- OPÇÕES
  
  Define ou redefine uma ou mais opções de tabela definidas pelo usuário.
- COMENTÁRIO table_comment
  
  String literal para descrever a tabela.
- TBLPROPERTIES
  
  Opcionalmente, define uma ou mais propriedades definidas pelo usuário.
- COTEJAMENTO PADRÃO default_collation_name
  
  Aplica-se a: Databricks SQL Databricks Runtime 16.3 e superior
  
  Define o agrupamento padrão a ser usado para:
  - STRING colunas e campos da tabela
  - DEFAULT expressão
  - O corpo de CREATE TABLE AS query
  As restrições do CHECK e as expressões de coluna geradas exigem um agrupamento padrão de UTF8_BINARY.
  
  Se não for especificado, o agrupamento padrão será UTF8_BINARY.
- COM ROW FILTER cláusula
  
  Aplica-se a: Databricks SQL Databricks Runtime 12.2 LTS e superior Unity Catalog somente
  
  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 é avaliada como booleana TRUE. Isso pode ser útil para fins de controle de acesso refinado, onde a função pode inspecionar a identidade ou as associações de grupo do usuário que invoca para decidir se deseja filtrar determinadas linhas.

AS consulta

Esta cláusula opcional preenche a tabela usando os dados de query. Quando especifica um query, não deve também especificar um table_specification. 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);

-- Creates a managed Iceberg table
> CREATE TABLE edu.enrollment.student (id INT, name STRING, age INT) USING ICEBERG;

-- 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 a table with a string column with a case-insensitive collation.
> CREATE TABLE names(name STRING COLLATE UNICODE_CI);

-- Create a table with a default collation and override for a specific column.
> CREATE TABLE names(name STRING, first_name STRING, id STRING COLLATE UTF8_BINARY) DEFAULT COLLATION UNICODE_CI;

-- 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;

Partilhar via

CREATE TABLE [USANDO]

Sintaxe

Parâmetros

Exemplos

Artigos relacionados

Comentários

Recursos adicionais