CREATE TABLE [USING]

Se aplica a: Databricks SQL Databricks Runtime

Define una tabla externa o administrada, opcionalmente mediante un origen de datos.

Sintaxis

{ { [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 de Databricks Runtime 16.1, START WITH debe preceder a INCREMENT BY.

Parámetros

• SUSTITUIR

  Si así se especifica, reemplaza la tabla y su contenido si ya existe. Esta cláusula solo se admite para las tablas Delta y Apache Iceberg.

  REPLACE conserva el historial de tabla así como los privilegios concedidos.

  Nota

  Azure Databricks recomienda encarecidamente usar REPLACE en lugar de quitar y volver a crear tablas.

• EXTERNO

  Si se especifica, crea una tabla externa. Al crear una tabla externa, también debe proporcionar una cláusula LOCATION. Cuando se quita una tabla externa, no se quitarán los archivos en LOCATION.

• SI NO EXISTE

  Si se especifica y ya existe una tabla con el mismo nombre, se omite la instrucción.

  IF NOT EXISTS no puede coexistir con REPLACE, lo que significa que CREATE OR REPLACE TABLE IF NOT EXISTS no está permitido.

• table_name

  Nombre de la tabla que se va a crear. El nombre no debe incluir una especificación temporal ni una especificación de opciones . Si el nombre no está completo, la tabla se crea en el esquema actual.

  Las tablas creadas en hive_metastore solo pueden contener caracteres ASCII alfanuméricos y caracteres de subrayado (INVALID_SCHEMA_OR_RELATION_NAME).

  Las tablas de Iceberg deben crearse en el Catálogo de Unity. No se admite la creación de tablas de Iceberg en hive_metastore.

• especificación_de_tabla

  Esta cláusula opcional define la lista de columnas y sus tipos, propiedades, descripciones y restricciones de columnas.

  Si no define columnas en el esquema de la tabla, debe especificar AS query o LOCATION.

  • column_identifier

    Nombre único para la columna.

    Los identificadores de columna de las tablas Delta sin propiedad de asignación de columnas ('delta.columnMapping.mode' = 'name') no deben contener espacios ni los siguientes caracteres: , ; { } ( ) \n \t = .

    Los identificadores de columna de las tablas AVRO deben comenzar con un guion bajo (_) o con una letra Unicode (incluidas las letras no ASCII) e ir seguido por una combinación de letras Unicode, dígitos y guiones bajos.

    Los identificadores de columna de las tablas ICEBERG deben ser únicos, insensibles a mayúsculas y seguir las reglas de identificadores SQL estándar. Evite usar espacios o caracteres especiales, ya que es posible que no sean compatibles con todos los motores de consulta.

  • tipo_de_columna

    Especifica el tipo de datos de la columna. No todos los tipos de datos que admite Azure Databricks son compatibles con todos los orígenes de datos.

  • NOT NULL

    Si se especifica, la columna no acepta NULL valores. Esta cláusula solo se admite para las tablas Delta e Iceberg.

  • INTERCALAR collation_name

    se aplica a: Databricks SQL Databricks Runtime 16.1 y versiones posteriores

    Opcionalmente, para STRINGcolumn_type, nombra la intercalación que se aplicará para las operaciones de comparación y ordenación en esta columna. La intercalación predeterminada es la tabla default_collation_name.

  • GENERADO SIEMPRE COMO ( expr )

    Cuando se especifica esta cláusula, el valor de esta columna viene determinado por el parámetro expr especificado.

    El DEFAULT COLLATION de la tabla debe ser UTF8_BINARY.

    expr puede estar compuesto por literales, identificadores de columna dentro de la tabla y funciones u operadores SQL integrados y deterministas, a excepción de lo siguiente:

    • Funciones de agregación
    • Funciones de ventana analítica
    • Funciones de ventana de categoría
    • Funciones de generador con valores de tabla
    • Columnas con una intercalación distinta de UTF8_BINARY

    Además, expr no deben contener ninguna subconsulta.

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

    Se aplica a: Databricks SQL Databricks Runtime 10.4 LTS y posterior

    Define una columna de identidad. Si escribe en la tabla y no proporciona valores para la columna de identidad, se le asignará automáticamente un valor único y estadísticamente creciente (o decreciente si step es negativo). Esta cláusula solo se admite para las tablas Delta. Además, solo se puede usar para columnas con el tipo de datos BIGINT.

    Los valores asignados automáticamente comienzan por start y se incrementan en step. Los valores asignados son únicos, pero no se garantiza que sean contiguos. Ambos parámetros son opcionales, con un valor predeterminado de 1. step no puede ser 0.

    Si los valores asignados automáticamente están fuera del intervalo del tipo de columna de identidad, se producirá un error en la consulta.

    Cuando se usa ALWAYS, no puede proporcionar sus propios valores para la columna de identidad.

    No se admiten estas operaciones:

    • PARTITIONED BY una columna de identidad
    • UPDATE una columna de identidad

    Nota

    Declarar una columna de identidad en una tabla deshabilita las transacciones simultáneas. Utilice columnas de identidad únicamente en casos en los que no se requieran escrituras simultáneas en la tabla de destino.

  • DEFAULT expresión_predeterminada

    Se aplica a: Databricks SQL Databricks Runtime 11.3 LTS y posterior

    Define un valor DEFAULT para la columna que se usa en INSERT, UPDATE y MERGE ... INSERT cuando no se especifica la columna.

    Si no se especifica ningún valor predeterminado, se aplicará DEFAULT NULL a las columnas que admiten un valor NULL.

    default_expression puede estar compuesto de literales y funciones u operadores de SQL integrados, con la excepción de:

    • Funciones de agregación
    • Funciones de ventana analítica
    • Funciones de ventana de categoría
    • Funciones de generador con valores de tabla

    Además, default_expression no deben contener ninguna subconsulta.

    DEFAULT es compatible con los orígenes CSV, JSON, PARQUET y ORC.

  • COMENTARIO column_comment

    Literal de cadena para describir la columna.

  • column_constraint

    Agrega una restricción de clave principal o clave externa a la columna de una tabla.

    No se admiten restricciones para las tablas del catálogo hive_metastore.

    Para agregar una restricción check a una tabla, use ALTER TABLE.

  • cláusula MASK

    Se aplica a: Databricks SQL Databricks Runtime 12.2 LTS y superior Solo Unity Catalog

    Importante

    Esta característica está en versión preliminar pública.

    Agrega una función de máscara de columna para anonimizar datos confidenciales. Todas las consultas posteriores de esa columna reciben el resultado de evaluar esa función sobre la columna en lugar del valor original de la columna. Esto puede ser útil para fines de control de acceso específicos en los que la función puede inspeccionar la identidad o las pertenencias a grupos del usuario que realiza la invocación, para así decidir si expurga el valor.

  • restricción_de_tabla

    Añade a la tabla una clave informativa primaria, o restricciones de clave informativa externa.

    No se admiten restricciones de clave para las tablas del catálogo hive_metastore.

    Para agregar una restricción check a una tabla, use ALTER TABLE.

• USANDO fuente_de_datos

  data_source puede ser un formato de archivo o un origen de datos JDBC federado.

  El formato del archivo debe ser uno de los siguientes:

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

  Para cualquier formato de archivo distinto de DELTA o ICEBERG, también debe especificar un LOCATION, a menos que el catálogo de tablas sea hive_metastore.

  Los orígenes de datos JDBC federados admitidos son los siguientes:

  • POSTGRESQL
  • SQLSERVER
  • MYSQL
  • BIGQUERY
  • NETSUITE
  • ORACLE
  • REDSHIFT
  • SNOWFLAKE
  • SQLDW
  • SYNAPSE
  • SALESFORCE
  • SALESFORCE_DATA_CLOUD
  • TERADATA
  • WORKDAY_RAAS
  • MONGODB

  Al especificar un origen JDBC federado, también debe especificar la cláusula OPTIONS con la información de conexión necesaria. Para más información sobre cómo consultar orígenes de datos federados véase Consulta de bases de datos con JDBC.

  Los siguientes formatos de archivo adicionales que se usarán para la tabla se admiten en Databricks Runtime:

  • JDBC
  • LIBSVM
  • El nombre de clase completo de una implementación de org.apache.spark.sql.sources.DataSourceRegister personalizada.

  Si se omite USING, el valor predeterminado es DELTA.

  Lo siguiente se aplica a: Databricks Runtime

  HIVE se admite para crear una tabla Hive SerDe en Databricks Runtime. Puede especificar el file_format y row_format específico de Hive mediante la cláusula OPTIONS, que es un mapa de cadenas que no distingue entre mayúsculas y minúsculas. option_keys son:

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

• cláusulas_tabla

  También puede especificar una ubicación, particiones, clústeres, opciones, comentarios y propiedades definidas por el usuario para la nueva tabla. Cada subcláusula solo se puede especificar una vez.

  • PARTICIONADO POR

    Cláusula opcional para crear particiones de la tabla por un subconjunto de columnas.

    Nota

    En el caso de las tablas Iceberg administradas, Azure Databricks no admite PARTITIONED BY. Use la agrupación en clústeres líquidos (CLUSTER BY) para optimizar el diseño de datos en su lugar. En el caso de las tablas Delta, si omite la definición de tabla, Azure Databricks coloca las columnas de partición al final de la tabla, aunque las enumere anteriormente en la especificación de columna.

  • CLUSTER BY

    Se aplica a: Databricks SQL Databricks Runtime 13.3 y versiones posteriores

    Una cláusula opcional para agrupar una tabla Delta o Iceberg por un subconjunto de columnas. Consulte Uso de clústeres líquidos para tablas. Para agrupar otras tablas, use clustered_by_clause.

    En el caso de las tablas de Iceberg, debe deshabilitar explícitamente los vectores de eliminación y los ID de fila al usar CLUSTER BY.

  No se puede combinar la agrupación en clústeres líquidos con PARTITIONED BY.

  • clustered_by_clause

    También puede agrupar la tabla o cada partición en un número fijo de cubos de hash mediante un subconjunto de las columnas.

    Esta cláusula no se admite para las tablas Delta o Iceberg. En su lugar, use CLUSTER BY.

    • AGRUPADO POR

      Especifica el conjunto de columnas por el que se agrupa cada partición, o bien la tabla si no se especifica la creación de particiones.

      • cluster_column

        Identificador que hace referencia a un column_identifier en la tabla. Si especifica más de una columna, no debe haber duplicados. Puesto que una agrupación en clústeres funciona en el nivel de partición, no debe nombrar una columna de partición también como columna de clúster.

    • ORDENADO POR

      También puede mantener un criterio de ordenación para las filas de un cubo.

      • sort_column

        Columna por la que se debe ordenar el cubo. La columna no debe ser de partición. Las columnas de ordenación deben ser únicas.

      • ASC or DESC

        También puede especificar si el orden que se aplica a sort_column es ascendente (ASC) o descendente (DESC). El valor predeterminado es ASC.

    • INTO num_buckets BUCKETS

      Literal INTEGER que especifica el número de cubos en los que se divide cada partición (o la tabla si no se especifica la creación de particiones).

  • LOCATION path [ WITH ( CREDENTIAL credential_name ) ]

    Ruta de acceso opcional al directorio donde se almacenan los datos de tabla, que podría ser una ruta de acceso en el almacenamiento distribuido. path debe ser un literal de CADENA. Si no especifica ninguna ubicación, la tabla se considera managed table, y Azure Databricks crea una ubicación de tabla predeterminada.

    Si se especifica una ubicación, la tabla se convierte en una tabla externa.

    En el caso de tablas que no residan en el catálogo hive_metastore, la tabla path debe estar protegida por una ubicación externa, a menos que se especifique una credencial de almacenamiento válida.

    No se pueden crear tablas externas en ubicaciones que se superpongan con la ubicación de las tablas administradas.

    En el caso de las tablas Delta, la tabla hereda su configuración de LOCATION si los datos ya existen en esa ruta de acceso. Como resultado, cualquier cláusula especificada TBLPROPERTIES, table_specification o PARTITIONED BY debe coincidir exactamente con los datos existentes en la ubicación Delta.

    En el caso de las tablas de Iceberg, no se admite la cláusula LOCATION. Las tablas Iceberg externas se registran automáticamente al crear un catálogo externo, y debe crear tablas de Iceberg administradas sin especificar una ubicación.

  • OPCIONES

    Este parámetro le permite establecer o restablecer una o varias opciones de tabla que defina el usuario.

  • COMENTARIO table_comment

    Literal de cadena para describir la tabla.

  • TBLPROPERTIES

    Este parámetro opcional le permite establecer una o más propiedades que defina el usuario.

  • INTERCALACIÓN PREDETERMINADA nombre_intercalación_predeterminada

    Se aplica a: Databricks SQL Databricks Runtime 16.3 y versiones posteriores

    Define la intercalación predeterminada que se va a usar para:

    • STRING columnas y campos de la tabla
    • Expresión DEFAULT
    • El cuerpo de CREATE TABLE AS query

    CHECK Las restricciones y expresiones de columna generadas requieren una intercalación predeterminada de UTF8_BINARY.

    Si no se especifica, la intercalación predeterminada es UTF8_BINARY.

  • CláusulaWITH ROW FILTER

    Se aplica a: Databricks SQL Databricks Runtime 12.2 LTS y superior Solo Unity Catalog

    Agrega una función de filtro de fila a la tabla. Todas las consultas posteriores de esa tabla recibirán un subconjunto de las filas donde la función se evalúa como TRUE booleano. Esto puede ser útil para fines de control de acceso específicos en los que la función puede inspeccionar la identidad o las pertenencias a grupos del usuario que realiza la invocación, para así decidir si se filtran ciertas filas.

• AS query

  Esta cláusula opcional rellena la tabla con los datos de query. Si especifica un parámetro query, no debe especificar también un parámetro table_specification. El esquema de tabla se deriva de la consulta.

  Tenga presente que Azure Databricks sobrescribe el origen de datos subyacente con los datos de la consulta de entrada para asegurarse de que la tabla que se crea contenga exactamente los mismos datos que la consulta.

Ejemplos

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

Artículos relacionados

• ALTER TABLE
• CONSTRAINT
• CLUSTER BY
• CREATE TABLE LIKE
• CREATE TABLE CLONE
• DROP TABLE
• PARTICIONADO POR
• Propiedades y opciones de tabla