E-MapReduce:Stream load

Sintaxis

curl --location-trusted -u <username>:<password> -XPUT <url>
(
    data_desc
)
[opt_properties]        

Parámetros

• <username>:<password>: El nombre de usuario y la contraseña de su clúster de StarRocks. Este parámetro es obligatorio. Si la cuenta no tiene contraseña, utilice <username>:.

• PUT: El método de solicitud HTTP. Este método es obligatorio. Stream Load solo admite PUT.

• <url>: La URL de la tabla de destino en StarRocks. Este parámetro es obligatorio. Utilice el siguiente formato: http://<fe_host>:<fe_http_port>/api/<database_name>/<table_name>/_stream_load.

  Parámetro	Obligatorio	Descripción
  <fe_host>	Sí	La dirección IP de un FE en el clúster de StarRocks.
  <fe_http_port>	Sí	El puerto HTTP del FE. Valor predeterminado: 18030. Puede encontrar el número de puerto buscando el parámetro http_port en la pestaña Configure de la página Services de StarRocks. Además, puede ejecutar el comando SHOW FRONTENDS para ver las direcciones IP y los puertos HTTP de los nodos FE.
  <database_name>	Sí	El nombre de la base de datos que contiene la tabla de destino.
  <table_name>	Sí	El nombre de la tabla de destino en StarRocks.

• desc: Describe las propiedades del archivo de datos de origen, como el nombre del archivo, el formato, el separador de columnas, el delimitador de filas, la partición de destino y la asignación de columnas a la tabla de StarRocks. El formato es el siguiente.

  -T <file_path>
  -H "format: CSV | JSON"
  -H "column_separator: <column_separator>"
  -H "row_delimiter: <row_delimiter>"
  -H "columns: <column1_name>[, <column2_name>, ... ]"
  -H "partitions: <partition1_name>[, <partition2_name>, ...]"
  -H "temporary_partitions: <temporary_partition1_name>[, <temporary_partition2_name>, ...]"
  -H "jsonpaths: [ \"<json_path1>\"[, \"<json_path2>\", ...] ]"
  -H "strip_outer_array: true | false"
  -H "json_root: <json_path>"
  -H "ignore_json_size: true | false"
  -H "compression: <compression_algorithm> | Content-Encoding: <compression_algorithm>"

  Los parámetros en data_desc se dividen en tres tipos: parámetros comunes, parámetros para CSV y parámetros para JSON.

  • Parámetros comunes

    Parámetro	Obligatorio	Descripción
    <file_path>	Sí	La ruta al archivo de datos de origen. El nombre del archivo puede incluir opcionalmente una extensión.
    format	No	El formato de los datos. Valores válidos: CSV y JSON. Valor predeterminado: CSV.
    partitions	No	Las particiones donde se cargarán los datos. Si no se especifica este parámetro, los datos se cargan en todas las particiones de la tabla.
    temporary_partitions	No	Las particiones temporales donde se cargarán los datos.
    columns	No	Especifica la asignación de columnas entre el archivo de datos de origen y la tabla de StarRocks. Este parámetro no es necesario si las columnas del archivo de datos de origen coinciden con el orden de las columnas en la tabla de destino. Si las columnas del archivo de origen no coinciden con el esquema de la tabla, debe usar este parámetro para definir la asignación. Puede asignar columnas de dos maneras: Ejemplo 1: La tabla tiene las columnas c1, c2, c3, pero las columnas del archivo de origen están en el orden c3, c2, c1. Debe especificar -H "columns: c3, c2, c1". Ejemplo 2: La tabla tiene tres columnas c1, c2, c3, y las primeras tres columnas del archivo de origen se asignan a ellas, pero el archivo tiene una cuarta columna innecesaria. En este caso, especifique -H "columns: c1, c2, c3, temp", usando un marcador de posición para la columna adicional. Ejemplo 3: La tabla tiene tres columnas year, month, day, pero el archivo de origen solo tiene una única columna de marca de tiempo en el formato 2018-06-01 01:02:03. Puede derivar las columnas de la tabla especificando -H "columns: col, year = year(col), month=month(col), day=day(col)".

  • Parámetros específicos de CSV

    Parámetro	Obligatorio	Descripción
    column_separator	No	El separador de columnas en el archivo de datos de origen. Valor predeterminado: \t. Para caracteres no imprimibles, anteponga \x y use un valor hexadecimal. Por ejemplo, para el separador de Hive \x01, especifique -H "column_separator:\x01".
    row_delimiter	No	El delimitador de filas en el archivo de datos de origen. Valor predeterminado: \n. Importante Al usar curl, el shell podría interpretar \n como una cadena literal en lugar de un carácter de nueva línea. En Bash, utilice la sintaxis $'string' para asegurar que las secuencias de escape como \n y \t se interpreten correctamente. Por ejemplo: -H $'row_delimiter:\n'.
    skip_header	No	El número de filas de encabezado que se omitirán al inicio del archivo CSV. El valor debe ser un número entero. Valor predeterminado: 0. Utilice este parámetro para ignorar filas de metadatos, como nombres de columnas o tipos, en el archivo CSV. Por ejemplo, establecer este parámetro en 1 omite la primera fila. El delimitador de filas utilizado aquí debe coincidir con el especificado en su comando de carga.
    where	No	Una condición para filtrar qué filas se cargarán. Por ejemplo, para cargar solo las filas donde la columna k1 es igual a 20180601, especifique -H "where: k1 = 20180601".
    max_filter_ratio	No	La proporción máxima de filas que pueden descartarse debido a errores de calidad de datos. Valor predeterminado: 0 (tolerancia cero). Nota Esto no aplica a las filas filtradas por la condición where.
    partitions	No	Las particiones de destino para la tarea de carga. Se recomienda especificar este parámetro si puede determinar las particiones de destino. Los datos de otras particiones se descartarán. Por ejemplo, para cargar datos en las particiones p1 y p2, especifique -H "partitions: p1, p2".
    timeout	No	El tiempo de espera para la tarea de carga, en segundos. Valor predeterminado: 600. El valor debe estar entre 1 y 259200.
    strict_mode	No	Habilita o deshabilita el modo estricto para esta tarea de carga. Valores válidos: false (predeterminado): El modo estricto está deshabilitado. true: El modo estricto está habilitado. Cuando se habilita, se aplica un filtrado estricto a las conversiones de tipo de columna durante la carga.
    timezone	No	La zona horaria para la tarea de carga. Valor predeterminado: Asia/Shanghai (UTC+08:00). Este parámetro afecta a todas las funciones relacionadas con la zona horaria utilizadas en la carga.
    exec_mem_limit	No	El límite de memoria para la tarea de carga. Valor predeterminado: 2 GB.

  • Parámetros específicos de JSON

    Parámetro	Obligatorio	Descripción
    jsonpaths	No	Especifica los campos que se extraerán de los datos JSON. Esto es necesario solo cuando necesita asignar campos de origen específicos a columnas de la tabla. El valor debe estar en formato JSON.
    strip_outer_array	No	Especifica si se debe eliminar la estructura de matriz más externa. Valores válidos: false (predeterminado): Conserva la estructura JSON original. Toda la matriz JSON se importa como un único valor. Por ejemplo, para los datos [{"k1" : 1, "k2" : 2},{"k1" : 3, "k2" : 4}], establecer strip_outer_array en false importa los datos como una sola matriz. true: Si los datos que se van a cargar son una matriz JSON, debe establecer strip_outer_array en true. Por ejemplo, para los datos [{"k1" : 1, "k2" : 2},{"k1" : 3, "k2" : 4}], establecer strip_outer_array en true importa los datos como dos filas separadas.
    json_root	No	Especifica el elemento raíz de los datos JSON que se importarán. Este parámetro es necesario solo cuando carga datos JSON haciendo coincidir campos. El valor debe ser una cadena JsonPath válida. Valor predeterminado: vacío, lo que significa que se importa todo el archivo JSON.
    ignore_json_size	No	Especifica si se debe omitir la comprobación de tamaño para el cuerpo JSON en la solicitud HTTP. Nota De forma predeterminada, el tamaño del cuerpo JSON en una solicitud HTTP no puede exceder los 100 MB. Si el tamaño supera este límite, se devuelve un error: "The size of this batch exceed the max size [104857600] of json type data data [8617627793]. Set ignore_json_size to skip check, although it may lead huge memory consuming." Para cargar archivos más grandes, agregue el encabezado "ignore_json_size:true" a su solicitud para omitir esta comprobación.
    compression, Content-Encoding	No	El algoritmo de compresión utilizado para el cuerpo de la solicitud. Algoritmos compatibles: GZIP, BZIP2, LZ4_FRAME y ZSTD. Por ejemplo: curl --location-trusted -u root: -v 'http://127.0.0.1:18030/api/db0/tbl_simple/_stream_load' \-X PUT -H "expect:100-continue" \-H 'format: json' -H 'compression: lz4_frame' -T ./b.json.lz4.

• opt_properties: Especifica parámetros opcionales para la importación. Los parámetros especificados se aplican a toda la tarea de importación.

  El formato es el siguiente:

  -H "label: <label_name>"
  -H "where: <condition1>[, <condition2>, ...]"
  -H "max_filter_ratio: <num>"
  -H "timeout: <num>"
  -H "strict_mode: true | false"
  -H "timezone: <string>"
  -H "load_mem_limit: <num>"
  -H "partial_update: true | false"
  -H "partial_update_mode: row | column"
  -H "merge_condition: <column_name>"

  Parámetro	Obligatorio	Descripción
  label	No	Una etiqueta única para la tarea de carga. StarRocks impide usar la misma etiqueta para más de una tarea exitosa. Puede usar etiquetas para evitar cargas duplicadas. StarRocks conserva las etiquetas de las tareas exitosas durante 30 minutos.
  where	No	Especifica una condición de filtro. StarRocks aplica este filtro a los datos después de cualquier transformación del parámetro columns. Solo se importan los datos que satisfacen la cláusula where. Por ejemplo, para importar solo las filas donde la columna k1 es 20180601, especifique -H "where: k1 = 20180601".
  max_filter_ratio	No	La proporción máxima de filas que pueden descartarse debido a errores de calidad de datos. Valor predeterminado: 0 (tolerancia cero). Nota Esto no aplica a las filas filtradas por la condición where.
  log_rejected_record_num	No	Especifica el número máximo de filas rechazadas que se registrarán debido a problemas de calidad de datos. Compatible desde la v3.1. Valores válidos: 0, -1 o un entero positivo. Valor predeterminado: 0. 0: No se registra ninguna fila rechazada. -1: Se registran todas las filas rechazadas. Un entero positivo, como n: Se registra un máximo de n filas rechazadas en cada nodo BE (o CN).
  timeout	No	Tiempo de espera de la tarea de carga en segundos. Valor predeterminado: 600. El valor debe estar entre 1 y 259200.
  strict_mode	No	Especifica si se debe habilitar el modo estricto para esta tarea de carga. false (predeterminado): El modo estricto está deshabilitado. true: El modo estricto está habilitado.
  timezone	No	La zona horaria para la tarea de carga. Valor predeterminado: Asia/Shanghai (UTC+08:00). Este parámetro afecta a todas las funciones relacionadas con la zona horaria utilizadas en la carga.
  load_mem_limit	No	El límite de memoria para la tarea de carga. Valor predeterminado: 2 GB.
  partial_update	No	Habilita actualizaciones parciales de columnas. Valores válidos: true y false. Valor predeterminado: false.
  partial_update_mode	No	Especifica el modo para actualizaciones parciales. Valores válidos: row y column. row (predeterminado): Modo de fila. Ideal para actualizaciones en tiempo real con muchas columnas en lotes pequeños. column: Modo de columna. Ideal para actualizaciones por lotes de pocas columnas en muchas filas. Este modo puede mejorar significativamente el rendimiento. Por ejemplo, si actualiza 10 de 100 columnas (10%) para todas las filas de una tabla, el modo de columna puede mejorar el rendimiento hasta 10 veces.
  merge_condition	No	Especifica el nombre de la columna que se usará como condición de actualización. Una actualización de fila solo ocurre si el valor de los nuevos datos para esta columna es mayor o igual al valor existente. Nota La columna especificada no debe formar parte de la clave principal. Esta función solo está disponible para tablas de clave principal.

Ejemplo

Este ejemplo carga data.csv en la tabla example_table de la base de datos load_test de un clúster de StarRocks. Para ver un ejemplo completo, consulte Complete data loading example.

curl --location-trusted -u "root:" \
     -H "Expect:100-continue" \
     -H "label:label2" \
     -H "column_separator: ," \
     -T data.csv -XPUT \
     http://172.17.**.**:18030/api/load_test/example_table/_stream_load

Valor de retorno

Cuando una tarea de carga finaliza, devuelve el resultado en formato JSON. A continuación se muestra un ejemplo.

{
    "TxnId": 9,
    "Label": "label2",
    "Status": "Success",
    "Message": "OK",
    "NumberTotalRows": 4,
    "NumberLoadedRows": 4,
    "NumberFilteredRows": 0,
    "NumberUnselectedRows": 0,
    "LoadBytes": 45,
    "LoadTimeMs": 235,
    "BeginTxnTimeMs": 101,
    "StreamLoadPlanTimeMs": 102,
    "ReadDataTimeMs": 0,
    "WriteDataTimeMs": 11,
    "CommitAndPublishTimeMs": 19
}

El valor de retorno incluye los siguientes parámetros:

wget "http://172.17.**.**:18040/api/_load_error_log?file=error_log_b74dccdcf0ceb4de_e82b2709c6c013ad"