CREATE TABLE [USING]

  • Artículo

Se aplica a:casilla marcada como Sí Databricks SQL casilla marcada como Sí 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 |
    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

    Si se especifica, reemplaza la tabla y su contenido si ya existe. Esta cláusula solo es compatible con tablas de Delta Lake.

    REPLACE conserva el historial de tablas.

    Nota:

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

  • EXTERNAL

    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.

  • IF NOT EXISTS

    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, por lo que no se admite CREATE OR REPLACE TABLE IF NOT EXISTS.

  • table_name

    Nombre de la tabla que se va a crear. El nombre no debe incluir una especificación temporal. 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).

  • table_specification

    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 de Delta Lake sin propiedad de asignación de columnas ('delta.columnMapping.mode' = 'name') no deben contener los caracteres ‘ ‘ (espacio), ‘,’, ‘;’, ‘{‘, ‘}’, ‘(‘, ‘)’. ‘n’, ‘t’, y ‘=’.

      Los identificadores de columna de la tabla AVRO deben comenzar con "" o una letra Unicode (incluidas las letras que no son ASCII) y deben ir seguidas de una combinación de "", letras Unicode y dígitos.

    • column_type

      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 aceptará valores NULL. Esta cláusula solo es compatible con tablas de Delta Lake.

    • GENERATED ALWAYS AS ( expr )

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

      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:

      expr tampoco debe contener ninguna subconsulta.

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

      Se aplica a:casilla marcada como sí Databricks SQL casilla marcada como Sí Databricks Runtime 10.4 LTS y versiones posteriores

      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 es compatible con tablas de Delta Lake. 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 Delta deshabilita las transacciones concurrentes. Utilice columnas de identidad únicamente en casos en los que no se requieran escrituras simultáneas en la tabla de destino.

    • DEFAULT default_expression

      Se aplica a:casilla marcada como sí Databricks SQL casilla marcada como Sí Databricks Runtime 11.3 LTS y versiones posteriores

      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, excepto:

      default_expression tampoco debe contener ninguna subconsulta.

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

    • COMMENT column_comment

      Literal de cadena para describir la columna.

    • column_constraint

      Importante

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

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

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

      Para agregar una restricción de comprobación a una tabla de Delta Lake, use ALTER TABLE.

    • Cláusula MASK

      se aplica a:casilla marcada como sí Databricks SQL casilla marcada como Sí Databricks Runtime 12.2 LTS y versiones posteriores solo casilla marcada como Sí 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 futuras desde esa columna recibirán 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 decidir si expurga el valor.

    • table_constraint

      Agrega una restricción de clave principal informativa o de clave externa informativa a la tabla de Delta Lake.

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

      Para agregar una restricción de comprobación a una tabla de Delta Lake, use ALTER TABLE.

  • USING data_source

    Formato de archivo que se va a usar para la tabla. data_source debe ser uno de los siguientes:

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

    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.

    Para cualquier data_source que no sea DELTA, también debe especificar LOCATION, a menos que el catálogo de tablas sea hive_metastore.

    Lo siguiente se aplica a: Databricks Runtime

    HIVE se admite para crear una tabla de 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

  • table_clauses

    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.

    • PARTITIONED BY

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

      Nota:

      Si no define una tabla Delta, las columnas de partición se colocan al final de la tabla, incluso si se definieron anteriormente en la especificación de columna. Considere la posibilidad de usar CLUSTER BY en lugar de PARTITIONED BY para las tablas de Delta Lake.

    • CLUSTER BY

      Se aplica a: casilla marcada como sí Databricks SQL casilla marcada como Sí Databricks Runtime 13.3 y versiones posteriores

      Una cláusula opcional para agrupar una tabla de Delta Lake por un subconjunto de columnas. Para agrupar otras tablas, use clustered_by_clause.

      La agrupación en clústeres líquidos de Delta Lake no se puede combinar 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.

      Las tablas de Delta Lake no admiten agrupación en clústeres.

      • CLUSTERED BY

        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.

      • SORTED BY

        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 o 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 una tabla de Delta Lake, la configuración de tabla se hereda de LOCATION hay datos presentes. Por lo tanto, si se especifican cláusulas TBLPROPERTIES, table_specification o PARTITIONED BY para tablas de Delta Lake, deben coincidir exactamente con los datos de ubicación de Delta Lake.

    • OPTIONS

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

    • COMMENT 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.

    • WITH Cláusula ROW FILTER

      se aplica a:casilla marcada como sí Databricks SQL casilla marcada como Sí Databricks Runtime 12.2 LTS y versiones posteriores solo casilla marcada como Sí Unity Catalog

      Importante

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

      Agrega una función de filtro de fila a la tabla. Todas las consultas futuras desde esa tabla recibirán un subconjunto de sus filas para las que la función se evalúa como un valor 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 decidir si se filtran determinadas 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);

-- 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 '/mnt/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));