Project: StarRocks (App Definition and Development / Database)
File: files.md

displayed_sidebar: "English" Defines data files in remote storage. From v3.1.0 onwards, StarRocks supports defining read-only files in remote storage using the table function FILES(). It can access remote storage with the path-related properties of the files, infers the table schema of the data in the files, and returns the data rows. You can directly query the data rows using , load the data rows into an existing table using , or create a new table and load the data rows into it using . From v3.2.0 onwards, FILES() supports writing data into files in remote storage. You can . Currently, the FILES() function supports the following data sources and file formats: Data sources: HDFS AWS S3 Google Cloud Storage Other S3-compatible storage system Microsoft Azure Blob Storage File formats: Parquet ORC CSV Data loading: ```SQL FILES( datalocation , dataformat [, schemadetect ] [, StorageCredentialParams ] [, columnsfrom_path ] ) ``` Data unloading: ```SQL FILES( datalocation , dataformat [, StorageCredentialParams ] , unloaddataparam ) ``` All parameters are in the `"key" = "value"` pairs. The URI used to access the files. You can specify a path or a file. To access HDFS, you need to specify this parameter as: ```SQL "path" = "hdfs://<hdfshost>:<hdfsport>/<hdfs_path>" -- Example: "path" = "hdfs://127.0.0.1:9000/path/file.parquet" ``` To access AWS S3: If you use the S3 protocol, you need to specify this parameter as: ```SQL "path" = "s3://<s3_path>" -- Example: "path" = "s3://path/file.parquet" ``` If you use the S3A protocol, you need to specify this parameter as: ```SQL "path" = "s3a://<s3_path>" -- Example: "path" = "s3a://path/file.parquet" ``` To access Google Cloud Storage, you need to specify this parameter as: ```SQL "path" = "s3a://<gcs_path>" -- Example: "path" = "s3a://path/file.parquet" ``` To access Azure Blob Storage: If your storage account allows access over HTTP, you need to specify this parameter as: ```SQL "path" = "wasb://<container>@<storageaccount>.blob.core.windows.net/<blobpath>" -- Example: "path" = "wasb://testcontainer@testaccount.blob.core.windows.net/path/file.parquet" ``` If your storage account allows access over HTTPS, you need to specify this parameter as: ```SQL "path" = "wasbs://<container>@<storageaccount>.blob.core.windows.net/<blobpath>" -- Example: "path" = "wasbs://testcontainer@testaccount.blob.core.windows.net/path/file.parquet" ``` The format of the data file. Valid values: `parquet`, `orc`, and `csv`. You must set detailed options for specific data file formats. Example for the CSV format: ```SQL "format"="csv", "csv.column_separator"="\\t", "csv.enclose"='"', "csv.skip_header"="1", "csv.escape"="\\" ``` Specifies the column separator used when the data file is in CSV format. If you do not specify this parameter, this parameter defaults to `\\t`, indicating tab. The column separator you specify using this parameter must be the same as the column separator that is actually used in the data file. Otherwise, the load job will fail due to inadequate data quality. Tasks that use Files() are submitted according to the MySQL protocol. StarRocks and MySQL both escape characters in the load requests. Therefore, if the column separator is an invisible character such as tab, you must add a backslash (`\`) preceding the column separator. For example, you must input `\\t` if the column separator is `\t`, and you must input `\\n` if the column separator is `\n`. Apache Hive files use `\x01` as their column separator, so you must input `\\x01` if the data file is from Hive. NOTE For CSV data, you can use a UTF-8 string, such as a comma (,), tab, or pipe (|), whose length does not exceed 50 bytes as a text delimiter. Null values are denoted by using

For example, a data file consists of three columns, and a record from that data file holds data in the first and third columns but no data in the second column. In this situation, you need to use `\N` in the second column to denote a null value. This means the record must be compiled as `a,\N,b` instead of `a,,b`. `a,,b` denotes that the second column of the record holds an empty string. Specifies the character that is used to wrap the field values in the data file according to RFC4180 when the data file is in CSV format. Type: single-byte character. Default value: `NONE`. The most prevalent characters are single quotation mark (`'`) and double quotation mark (`"`). All special characters (including row separators and column separators) wrapped by using the `enclose`-specified character are considered normal symbols. StarRocks can do more than RFC4180 as it allows you to specify any single-byte character as the `enclose`-specified character. If a field value contains an `enclose`-specified character, you can use the same character to escape that `enclose`-specified character. For example, you set `enclose` to `"`, and a field value is `a "quoted" c`. In this case, you can enter the field value as `"a ""quoted"" c"` into the data file. Specifies whether to skip the first rows of the data file when the data file is in CSV format. Type: INTEGER. Default value: `0`. In some CSV-formatted data files, the first rows at the beginning are used to define metadata such as column names and column data types. By setting the `skip_header` parameter, you can enable StarRocks to skip the first rows of the data file during data loading. For example, if you set this parameter to `1`, StarRocks skips the first row of the data file during data loading. The first rows at the beginning in the data file must be separated by using the row separator that you specify in the load statement. Specifies the character that is used to escape various special characters, such as row separators, column separators, escape characters, and `enclose`-specified characters, which are then considered by StarRocks to be common characters and are parsed as part of the field values in which they reside. Type: single-byte character. Default value: `NONE`. The most prevalent character is slash (`\`), which must be written as double slashes (`\\`) in SQL statements. NOTE The character specified by `escape` is applied to both inside and outside of each pair of `enclose`-specified characters. Two examples are as follows: When you set `enclose` to `"` and `escape` to `\`, StarRocks parses `"say \"Hello world\""` into `say "Hello world"`. Assume that the column separator is comma (`,`). When you set `escape` to `\`, StarRocks parses `a, b\, c` into two separate field values: `a` and `b, c`. From v3.2 onwards, FILES() supports automatic schema detection and unionization of the same batch of data files. StarRocks first detects the schema of the data by sampling certain data rows of a random data file in the batch. Then, StarRocks unionizes the columns from all the data files in the batch. You can configure the sampling rule using the following parameters: `autodetectsample_files`: the number of random data files to sample in each batch. Range: [0, + ]. Default: `1`. `autodetectsample_rows`: the number of data rows to scan in each sampled data file. Range: [0, + ]. Default:

After the sampling, StarRocks unionizes the columns from all the data files according to these rules: For columns with different column names or indices, each column is identified as an individual column, and, eventually, the union of all individual columns is returned. For columns with the same column name but different data types, they are identified as the same column but with a general data type on a relative fine granularity level. For example, if the column `col1` in file A is INT but DECIMAL in file B, DOUBLE is used in the returned column. Generally, the STRING type can be used to unionize all data types. If StarRocks fails to unionize all the columns, it generates a schema error report that includes the error information and all the file schemas. CAUTION All data files in a single batch must be of the same file format. The authentication information used by StarRocks to access your storage system. StarRocks currently supports accessing HDFS with the simple authentication, accessing AWS S3 and GCS with the IAM user-based authentication, and accessing Azure Blob Storage with Shared Key. Use the simple authentication to access HDFS: ```SQL "hadoop.security.authentication" = "simple", "username" = "xxxxxxxxxx", "password" = "yyyyyyyyyy" ``` | Key | Required | Description | | | | | | hadoop.security.authentication | No | The authentication method. Valid value: `simple` (Default). `simple` represents simple authentication, meaning no authentication. | | username | Yes | The username of the account that you want to use to access the NameNode of the HDFS cluster. | | password | Yes | The password of the account that you want to use to access the NameNode of the HDFS cluster. | Use the IAM user-based authentication to access AWS S3: ```SQL "aws.s3.access_key" = "xxxxxxxxxx", "aws.s3.secret_key" = "yyyyyyyyyy", "aws.s3.region" = "<s3_region>" ``` | Key | Required | Description | | -- | | | | aws.s3.access_key | Yes | The Access Key ID that you can use to access the Amazon S3 bucket. | | aws.s3.secret_key | Yes | The Secret Access Key that you can use to access the Amazon S3 bucket. | | aws.s3.region | Yes | The region in which your AWS S3 bucket resides. Example: `us-west-2`. | Use the IAM user-based authentication to access GCS: ```SQL "fs.s3a.access.key" = "xxxxxxxxxx", "fs.s3a.secret.key" = "yyyyyyyyyy", "fs.s3a.endpoint" = "<gcs_endpoint>" ``` | Key | Required | Description | | -- | | | | fs.s3a.access.key | Yes | The Access Key ID that you can use to access the GCS bucket. | | fs.s3a.secret.key | Yes | The Secret Access Key that you can use to access the GCS bucket.| | fs.s3a.endpoint | Yes | The endpoint that you can use to access the GCS bucket. Example: `storage.googleapis.com`. | Use Shared Key to access Azure Blob Storage: ```SQL "azure.blob.storageaccount" = "<storageaccount>", "azure.blob.sharedkey" = "<sharedkey>" ``` | Key | Required | Description | | -- | | | | azure.blob.storage_account | Yes | The name of the Azure Blob Storage account. | | azure.blob.shared_key | Yes | The Shared Key that you can use to access the Azure Blob Storage account. | From v3.2 onwards, StarRocks can extract the value of a key/value pair from the file path as the value of a column. ```SQL "columnsfrompath" = "<column_name> [, ...]" ``` Suppose the data file file1 is stored under a path in the format of `/geo/country=US/city=LA/`. You can specify the `columnsfrompath` parameter as `"columnsfrompath" = "country, city"` to extract the geographic information in the file path as the value of columns that are returned. For further instructions, see Example

From v3.2 onwards, FILES() supports defining writable files in remote storage for data unloading. For detailed instructions, see . ```sql -- Supported from v3.2 onwards. unloaddataparam::= "compression" = "<compression_method>", "partitionby" = "<columnname> [, ...]", "single" = { "true" | "false" } ``` | Key | Required | Description | | - | | | | compression | Yes | The compression method to use when unloading data. Valid values:<ul><li>`uncompressed`: No compression algorithm is used.</li><li>`gzip`: Use the gzip compression algorithm.</li><li>`snappy`: Use the SNAPPY compression algorithm.</li><li>`zstd`: Use the Zstd compression algorithm.</li><li>`lz4`: Use the LZ4 compression algorithm.</li></ul> | | partition_by | No | The list of columns that are used to partition data files into different storage paths. Multiple columns are separated by commas (,). FILES() extracts the key/value information of the specified columns and stores the data files under the storage paths featured with the extracted key/value pair. For further instructions, see Example 5. | | single | No | Whether to unload the data into a single file. Valid values:<ul><li>`true`: The data is stored in a single data file.</li><li>`false` (Default): The data is stored in multiple files if the amount of data unloaded exceeds 512 MB.</li></ul> | From v3.2 onwards, FILES() further supports complex data types including ARRAY, JSON, MAP, and STRUCT in addition to basic data types. Example 1: Query the data from the Parquet file parquet/par-dup.parquet within the AWS S3 bucket `inserttest`: ```Plain MySQL > SELECT * FROM FILES( "path" = "s3://inserttest/parquet/par-dup.parquet", "format" = "parquet", "aws.s3.access_key" = "XXXXXXXXXX", "aws.s3.secret_key" = "YYYYYYYYYY", "aws.s3.region" = "us-west-2" ); +++ | c1 | c2 | +++ | 1 | {"1": "key", "1": "1", "111": "1111", "111": "aaaa"} | | 2 | {"2": "key", "2": "NULL", "222": "2222", "222": "bbbb"} | +++ 2 rows in set (22.335 sec) ``` Example 2: Insert the data rows from the Parquet file parquet/insert_wiki_edit_append.parquet within the AWS S3 bucket `inserttest` into the table `insertwikiedit`: ```Plain MySQL > INSERT INTO insertwikiedit SELECT * FROM FILES( "path" = "s3://inserttest/parquet/insertwikiedit_append.parquet", "format" = "parquet", "aws.s3.access_key" = "XXXXXXXXXX", "aws.s3.secret_key" = "YYYYYYYYYY", "aws.s3.region" = "us-west-2" ); Query OK, 2 rows affected (23.03 sec) {'label':'insert_d8d4b2ee-ac5c-11ed-a2cf-4e1110a8f63b', 'status':'VISIBLE', 'txnId':'2440'} ``` Example 3: Create a table named `ctaswikiedit` and insert the data rows from the Parquet file parquet/insert_wiki_edit_append.parquet within the AWS S3 bucket `inserttest` into the table: ```Plain MySQL > CREATE TABLE ctaswikiedit AS SELECT * FROM FILES( "path" = "s3://inserttest/parquet/insertwikiedit_append.parquet", "format" = "parquet", "aws.s3.access_key" = "XXXXXXXXXX", "aws.s3.secret_key" = "YYYYYYYYYY", "aws.s3.region" = "us-west-2" ); Query OK, 2 rows affected (22.09 sec) {'label':'insert_1a217d70-2f52-11ee-9e4a-7a563fb695da', 'status':'VISIBLE', 'txnId':'3248'} ``` Example 4: Query the data from the Parquet file /geo/country=US/city=LA/file1.parquet (which only contains two columns -`id` and `user`), and extract the key/value information in its path as columns returned. ```Plain SELECT * FROM FILES( "path" = "hdfs://xxx.xx.xxx.xx:9000/geo/country=US/city=LA/file1.parquet", "format" = "parquet", "hadoop.security.authentication" = "simple", "username" = "xxxxx", "password" = "xxxxx", "columnsfrompath" = "country, city" ); +++++ | id | user | country | city | +++++ | 1 | richard | US | LA | | 2 | amber | US | LA | +++++ 2 rows in set (3.84 sec) ``` Example 5: Unload all data rows in `salesrecords` as multiple Parquet files under the path **/unload/partitioned/** in the HDFS cluster. These files are stored in different subpaths distinguished by the values in the column `salestime`. ```SQL INSERT INTO FILES( "path" = "hdfs://xxx.xx.xxx.xx:9000/unload/partitioned/", "format" = "parquet", "hadoop.security.authentication" = "simple", "username" = "xxxxx", "password" = "xxxxx", "compression" = "lz4", "partitionby" = "salestime" ) SELECT * FROM sales_records; ```