Todos los productos
Search

Este producto

    ApsaraDB for ClickHouse:Importar datos desde OSS

    Centro de documentos

    ApsaraDB for ClickHouse:Importar datos desde OSS

    Última actualización: Sep 05, 2026

    Importe datos desde Object Storage Service (OSS) a Alibaba Cloud ClickHouse mediante un motor de tabla o una función de tabla para consultar, analizar y procesar registros.

    Requisitos previos

    • Active Object Storage Service (OSS). Para obtener más información, consulte Activate OSS.

    • Debe haber creado un bucket en la misma región que el clúster de Alibaba Cloud ClickHouse. Para ver las instrucciones sobre cómo crear un bucket, consulte Create a bucket.

    • La cuenta utilizada para acceder a OSS debe tener permisos de lectura sobre los objetos del bucket. Para obtener más información, consulte Overview.

    Preparación de datos

    Guarde los siguientes datos de prueba como test.csv y cárguelos en OSS. El separador de columnas predeterminado es la coma (,). Para ver las instrucciones de carga, consulte Upload files.

    1,yang,32,shanghai,http://example1.com
2,wang,22,beijing,http://example2.com
3,xiao,23,shenzhen,http://example3.com
4,jess,45,hangzhou,http://example4.com
5,jack,14,shanghai,http://example5.com
6,tomy,25,hangzhou,http://example6.com
7,lucy,45,shanghai,http://example7.com
8,tengyin,26,shanghai,http://example8.com
9,wangli,27,shenzhen,http://example9.com
10,xiaohua,37,shanghai,http://example10.com

    Procedimiento

    1. Conéctese al clúster de Alibaba Cloud ClickHouse. Para obtener más información, consulte Connect to a cluster.

    2. Cree una tabla local llamada oss_test_tbl_local.

      Importante

      • El esquema de la tabla de Alibaba Cloud ClickHouse debe coincidir con el esquema de la tabla externa de OSS y con el formato de los datos en OSS. Para evitar fallos de análisis sintáctico y excepciones en el clúster, gestione los campos nulos con cuidado.

      • Seleccione la sentencia CREATE TABLE adecuada según la configuración de réplicas de su clúster. Puede consultar esta configuración en la página Cluster Information, dentro de la sección Cluster Properties de la consola.

      • Puede seleccionar un motor de tabla según sus necesidades empresariales. Para obtener más información, consulte Table engines.

      Single-replica edition

      CREATE TABLE oss_test_tbl_local ON CLUSTER default
(
id UInt8,
user_name String,
age UInt16,
city String,
access_url String
)
ENGINE = MergeTree()
ORDER BY id;

      Double-replica edition

      CREATE TABLE oss_test_tbl_local ON CLUSTER default
(
id UInt8,
user_name String,
age UInt16,
city String,
access_url String
)
ENGINE = ReplicatedMergeTree('/clickhouse/tables/{database}/{table}/{shard}', '{replica}')
ORDER BY id;

    3. (Opcional) Cree una tabla distribuida llamada oss_test_tbl_distributed.

      Nota

      Cree una tabla distribuida si desea distribuir los datos entre todas las tablas locales del clúster.

      CREATE TABLE oss_test_tbl_distributed ON CLUSTER default
(
id UInt8,
user_name String,
age UInt16,
city String,
access_url String
)
ENGINE = Distributed(default, default, oss_test_tbl_local, rand());

    4. Importe datos desde OSS a Alibaba Cloud ClickHouse.

      Alibaba Cloud ClickHouse admite dos métodos para importar datos desde OSS: motores de tabla y funciones de tabla.

      Importante

      Seleccione la sentencia adecuada según la versión de su clúster. Puede consultar la versión en la página Cluster Information, dentro de la sección Cluster Properties de la consola.

      Método 1: Uso de un motor de tabla

      1. Cree una tabla externa de OSS llamada oss_test_tbl.

        Sintaxis para versiones anteriores a la 22.8

        CREATE TABLE <table_name> [ON CLUSTER cluster]
(
'col_name1' col_type1,
'col_name2' col_type2,
...
)
ENGINE = OSS('<oss-endpoint>', '<access-key-id>', '<access-key-secret>', '<oss-file-path>', '<file-format-name>');

        Sintaxis para la versión 22.8 y posteriores

        CREATE TABLE <table_name> [ON CLUSTER cluster]
(
'col_name1' col_type1,
'col_name2' col_type2,
...
)
ENGINE = OSS('https://<BucketName>.<oss-endpoint>/<file-name>', '<access-key-id>', '<access-key-secret>', '<file-format-name>');

        Parámetros:

        Parámetro

        Descripción

        table_name

        Nombre de la tabla.

        ON CLUSTER

        Crea una tabla local en cada nodo. Establezca este parámetro como ON CLUSTER default.

        col_name1,col_name2

        Nombres de las columnas.

        col_type1,col_type2

        Tipos de datos de las columnas.

        Importante

        El esquema de la tabla externa de OSS debe coincidir con los datos almacenados en OSS.

        BucketName

        Nombre del bucket.

        oss-endpoint

        Endpoint utilizado para acceder a OSS. Para obtener más información, consulte Regions and endpoints.

        Importante

        Asegúrese de que el bucket y su clúster de Alibaba Cloud ClickHouse se encuentren en la misma región, y acceda a OSS a través de una Virtual Private Cloud (VPC).

        file-name

        Nombre del archivo.

        access-key-id

        AccessKey ID utilizado para acceder a los datos en OSS. Para obtener información sobre cómo conseguir un AccessKey ID, consulte Obtain an AccessKey pair.

        access-key-secret

        AccessKey Secret utilizado para acceder a los datos en OSS. Para obtener información sobre cómo conseguir un AccessKey Secret, consulte Obtain an AccessKey pair.

        oss-file-path

        Ruta de almacenamiento del archivo. La ruta suele tener el formato oss://<bucket-name>/<path-to-file>.

        Nota

        El parámetro oss-file-path admite coincidencias aproximadas mediante comodines. Para obtener más información, consulte Wildcard matching for OSS storage paths.

        file-format-name

        Formato del archivo. Este tema utiliza CSV como ejemplo.

        Sentencias de ejemplo:

        Ejemplo para versiones anteriores a la 22.8

        CREATE TABLE oss_test_tbl on cluster default
(
id UInt8,
user_name String,
age UInt16,
city String,
access_url String
)
ENGINE = OSS('oss-cn-shanghai-internal.aliyuncs.com', 'LTAI****************', 'yourAccessKeySecret', 'oss://testBucketName/test.csv', 'CSV');

        Ejemplo para la versión 22.8 y posteriores

        CREATE TABLE oss_test_tbl on cluster default
(
id UInt8,
user_name String,
age UInt16,
city String,
access_url String
)
ENGINE = OSS('http://testBucketName.oss-cn-shanghai-internal.aliyuncs.com/test.csv', 'STS.****************', 'STS.****************','CSV')

      2. Importe datos desde la tabla externa de OSS oss_test_tbl hacia la tabla distribuida oss_test_tbl_distributed.

        Nota

        Si solo necesita importar datos a una tabla local, reemplace el nombre de la tabla distribuida por el de la tabla local en la sentencia INSERT.

        INSERT INTO oss_test_tbl_distributed SELECT * FROM oss_test_tbl;

        Si su archivo CSV utiliza un delimitador distinto a la coma (,), use la configuración format_csv_delimiter en la sentencia INSERT para especificarlo. Por ejemplo, si el archivo usa una barra vertical (|) como delimitador, ejecute la siguiente sentencia:

        INSERT INTO oss_test_tbl_distributed SELECT * FROM oss_test_tbl settings format_csv_delimiter='|';

      Método 2: Uso de una función de tabla

      Sintaxis para versiones anteriores a la 22.8

      INSERT INTO <table_name> SELECT * FROM oss('<oss-endpoint>', '<access-key-id>', '<access-key-secret>', '<oss-file-path>', '<file-format-name>', '<col_name> <col_type>(,...)');

      Sintaxis para la versión 22.8 y posteriores

      INSERT INTO <table_name> SELECT * FROM oss('https://<BucketName>.<oss-endpoint>/<file-name>','<access-key-id>', '<access-key-secret>', '<file-format-name>', '<col_name> <col_type>(,...)');

      Para obtener más información sobre los parámetros, consulte Parameter descriptions.

      Sentencias de ejemplo:

      Ejemplo para versiones anteriores a la 22.8

      INSERT INTO oss_test_tbl_distributed SELECT * FROM oss('oss-cn-shanghai-internal.aliyuncs.com', 'LTAI****************', 'yourAccessKeySecret', 'oss://testBucketName/test.csv', 'CSV', 'id UInt8, user_name String, age UInt16, city String, access_url String');

      Ejemplo para la versión 22.8 y posteriores

      INSERT INTO oss_test_tbl_distributed SELECT * FROM oss('http://testBucketName.oss-cn-shanghai-internal.aliyuncs.com/test.csv', 'STS.****************', 'STS.****************', 'CSV', 'id UInt8, user_name String, age UInt16, city String, access_url String');

      Si su archivo CSV utiliza un delimitador distinto a la coma (,), use la configuración format_csv_delimiter en la sentencia INSERT para especificarlo. Por ejemplo, si el archivo usa una barra vertical (|) como delimitador, ejecute la siguiente sentencia:

      INSERT INTO oss_test_tbl_distributed SELECT * FROM oss('<oss-endpoint>', '<access-key-id>', '<access-key-secret>', '<oss-file-path>', '<file-format-name>',  '<col_name> <col_type>(,...)') settings format_csv_delimiter='|';

    5. Consulte la tabla distribuida oss_test_tbl_distributed para comprobar la importación de datos.

      SELECT * FROM oss_test_tbl_distributed;

      Resultado esperado:

      ┌─id─┬─user_name─┬──age──┬───city─────┬─────access_url────────┐
│  1 │  yang     │   32  │  shanghai  │  http://example1.com  │
│  2 │  wang     │   22  │  beijing   │  http://example2.com  │
│  3 │  xiao     │   23  │  shenzhen  │  http://example3.com  │
│  4 │  jess     │   45  │  hangzhou  │  http://example4.com  │
│  5 │  jack     │   14  │  shanghai  │  http://example5.com  │
│  6 │  tomy     │   25  │  hangzhou  │  http://example6.com  │
│  7 │  lucy     │   45  │  shanghai  │  http://example7.com  │
│  8 │  tengyin  │   26  │  shanghai  │  http://example8.com  │
│  9 │  wangli   │   27  │  shenzhen  │  http://example9.com  │
│ 10 │  xiaohua  │   37  │  shanghai  │  http://example10.com │
└────┴───────────┴───────┴────────────┴───────────────────────┘

    Coincidencia de comodines para rutas de almacenamiento de OSS

    Para simplificar el análisis de varios archivos pequeños que comparten una convención de nombres, el parámetro oss-file-path admite los siguientes comodines:

    • *: Coincide con cualquier nombre de archivo o directorio. Por ejemplo, /dir/* coincide con todos los archivos del directorio /dir.

    • {x,y,z}: Coincide con cualquier valor incluido entre llaves. Por ejemplo, file_{x,y,z} coincide con file_x, file_y o file_z.

    • {num1..num2}: Coincide con cualquier valor dentro del rango expandido de num1 a num2. Por ejemplo, file_{1..3} coincide con file_1, file_2 y file_3.

    • ?: Coincide con cualquier carácter individual. Por ejemplo, file_? coincide con file_a, file_b, file_c, etc.

    Ejemplo

    Los archivos cargados utilizan la siguiente estructura de directorios.

    oss://testBucketName/
               doc-data/
                    oss-import/
                        small_files/
                            access_log_csv_1.txt
                            access_log_csv_2.txt
                            access_log_csv_3.txt

    Ejemplos:

    • oss://testBucketName/doc-data/oss-import/small_files/*

    • oss://testBucketName/doc-data/oss-import/small_files/access*

    • oss://testBucketName/doc-data/oss-import/small_files/access_log_csv_{1,2,3}.txt

    • oss://testBucketName/doc-data/oss-import/*/access_log_csv_{1,2,3}.txt

    • oss://testBucketName/doc-data/oss-import//

    • oss://testBucketName/doc-data/oss-import/*/access_log_csv_{1..3}.txt

    • oss://testBucketName/doc-data/oss-import/*/access_log_csv_?.txt