How to Bulk Load Vectors

Example 1a - Using LOAD DATA to Load Parquet Data from S3

The following command loads a parquet file stored in S3 to the vectors table. This example uses LOAD DATA , which is more efficient than loading data using INSERT statements. This command can be run as is because s3://singlestore-docs-examples-datasets is an public bucket.

LOAD DATA S3
's3://singlestore-docs-example-datasets/vecs/vec_f32_data.parquet'
CONFIG '{"region":"us-east-1"}'
CREDENTIALS '{}'
INTO TABLE vectors
FORMAT PARQUET
(id <- id, @v <-vec)
SET vec = @v:>BLOB:>VECTOR(4, F32);

Note the last line of this command which uses a set of casts to load Parquet data into the VECTOR attribute: SET vec = @v:>BLOB:>VECTOR(4, F32). By default, LOAD DATA expects vector data to be in textual JSON array notation. The casts in the SET clause override this, and allow more efficient assignment directly from binary data.

Run the following SQL statement to verify that the data was loaded.

SELECT id, vec 
FROM vectors
ORDER BY id;

+------+---------------------------------------------------+
| id   | vec                                               |
+------+---------------------------------------------------+
|    1 | [0.449999988,0.550000012,0.495000005,0.5]         |
|    2 | [0.100000001,0.800000012,0.200000003,0.555000007] |
|    3 | [-0.5,-0.0299999993,-0.100000001,0.860000014]     |
|    4 | [0.5,0.300000012,0.806999981,0.100000001]         |
+------+---------------------------------------------------+

The results do not exactly match the vector values listed at the beginning of this example because elements in the VECTOR data type are stored as floating-point numbers and the vector values are not perfectly representable in floating-point representation.

To experiment further and use your own data file, follow the instructions in the Example 4 - Export Vector Data in Parquet and Hexadecimal section.

Example 1b - Using a Pipeline to Load Parquet Data from S3

You can also use a pipeline to load data from S3. This example is the same as Example 1a, except that a pipeline is used to load the data.

Create a pipeline to load the Parquet data into the vectors table.

CREATE PIPELINE vec_pipeline_pqt AS
LOAD DATA S3
's3://singlestore-docs-example-datasets/vecs/vec_f32_data.parquet'
CONFIG '{"region":"us-east-1"}'
CREDENTIALS '{}'
INTO TABLE vectors
FORMAT PARQUET
(id <- id, @v <-vec)
SET vec = @v:>BLOB:>VECTOR(4, F32);

This command uses CREATE PIPELINE and will result in an error if the pipeline already exists. If you want to update a pipeline that exists and may be running, use the syntax CREATE OR REPLACE PIPELINE. Refer to CREATE PIPELINE for more information.

Start the pipeline.

START PIPELINE vec_pipeline_pqt FOREGROUND;

The command above starts a pipeline in the FOREGROUND so that errors will be displayed in the client. If you are using pipelines that will run continuously, consider starting pipelines in the background by omitting the FOREGROUND keyword. Refer to START PIPELINE for more information.

Once the pipeline has completed, verify that the data has been loaded.

SELECT id, vec 
FROM vectors
ORDER BY id;

+------+---------------------------------------------------+
| id   | vec                                               |
+------+---------------------------------------------------+
|    1 | [0.449999988,0.550000012,0.495000005,0.5]         |
|    2 | [0.100000001,0.800000012,0.200000003,0.555000007] |
|    3 | [-0.5,-0.0299999993,-0.100000001,0.860000014]     |
|    4 | [0.5,0.300000012,0.806999981,0.100000001]         |
+------+---------------------------------------------------+

Once a pipeline is no longer needed, it can be dropped.

DROP PIPELINE vec_pipeline_pqt;

If you have started a pipeline in the background (by omitting the FOREGROUND keyword), you can stop the pipeline instead of, or before, dropping it. Stopping a pipeline allows the pipeline to be used later, dropping a pipeline removes the pipeline from the system. Stopping is applicable for background pipelines only. Refer to STOP PIPELINE and DROP PIPELINE for more information.

Example 1c - Loading Data in Parquet Format from a Local File

Use the following SQL statement to load Parquet data from a local file into the vectors table. For this example, place the Parquet file in a location accessible to your SQL client process and replace the path, '/tmp/vec_f32_data.parquet', with the path to your text file.

LOAD DATA LOCAL INFILE '/tmp/vec_f32_data.parquet'
INTO TABLE vectors
FORMAT PARQUET
(id <- id, @v <-vec)
SET vec = @v:>BLOB:>VECTOR(4, F32);

Refer to LOAD DATA for more information on using LOAD DATA LOCAL.

To generate a Parquet file to use with this command, follow the instructions in the Example 4 - Export Vector Data in Parquet and Hexadecimal section.

Example 2a - Using a Pipeline to Load Data in Hexadecimal from S3

This example uses the vectors table created earlier, so before running this example, delete data from the vectors table to prevent duplicate records.

TRUNCATE vectors;

The following shows loading the data with vectors encoded in hexadecimal into the vectors table.

The command below can be run as is because s3://singlestore-docs-example-datasets/ is an public bucket.

CREATE PIPELINE vec_pipeline_hex AS
LOAD DATA S3
's3://singlestore-docs-example-datasets/vecs/vec_f32_data_hex.csv'
CONFIG '{"region":"us-east-1"}'
CREDENTIALS '{}'
INTO TABLE vectors
FORMAT CSV(id, @v)
SET vec = UNHEX(@v):>VECTOR(4,F32);

Note the last line of this command uses the UNHEX function and a cast to load hexadecimal data into a VECTOR attribute.

FORMAT CSV is the default and is not required in this query. We include it for clarity and to differentiate from the query for loading Parquet data. In addition, note that the column labelling format for CSV, (id, @v) in this case, is different than the column labelling format for Parquet (id ->- id, @v -> vec) in the previous example. Refer to LOAD DATA for more detail.

Start the pipeline.

START PIPELINE vec_pipeline_hex FOREGROUND;

Once the data load has completed, verify that the data was loaded using the following SQL.

SELECT * 
FROM vectors
ORDER BY id;

+------+---------------------------------------------------+
| id   | vec                                               |
+------+---------------------------------------------------+
|    1 | [0.449999988,0.550000012,0.495000005,0.5]         |
|    2 | [0.100000001,0.800000012,0.200000003,0.555000007] |
|    3 | [-0.5,-0.0299999993,-0.100000001,0.860000014]     |
|    4 | [0.5,0.300000012,0.806999981,0.100000001]         |
+------+---------------------------------------------------+

The results do not exactly match the vector values listed, because elements in the VECTOR data type are stored as floating-point numbers and the vector values are not perfectly representable in floating-point representation.

Once a pipeline is no longer needed it can be dropped.

DROP PIPELINE vec_pipeline_hex;

If you have started a pipeline in the background (by omitting the FOREGROUND keyword), you can stop the pipeline instead of, or before, dropping it. Stopping a pipeline allows the pipeline to be used later, dropping a pipeline removes the pipeline from the system. Stopping is applicable for background pipelines only. Refer to STOP PIPELINE and DROP PIPELINE for more information.

To experiment with your own data files and bucket, refer to Example 4 - Export Vector Data in Parquet and Hexadecimal and Example 5 - Generate Vector Data.

Example 2b - Loading Data in Hexadecimal from a Local File

Use the following SQL statement to load the data with vectors encoded in hexadecimal into the vectors table. For this example, place the hexadecimal data show at the beginning of this section in a local file accessible to your SQL client and replace '/tmp/vec_f32_data_hex.csv' with the path to your text file.

As with the example above, the command below uses UNHEX and a cast to load hexadecimal data into a VECTOR attribute.

LOAD DATA LOCAL INFILE '/tmp/vec_f32_data_hex.csv'
INTO TABLE vectors
FORMAT CSV
(id, @v)
SET vec = UNHEX(@v):>VECTOR(4,F32);

Example 3a - Using a PIPELINE to Load Vector Data in JSON Format from S3

The PIPELINE below loads this data into the vectors_i16 table. The command can be run as is because s3://singlestore-docs-example-datasets/ is a public bucket.

CREATE PIPELINE vec_i16_pipeline AS
LOAD DATA S3
's3://singlestore-docs-example-datasets/vecs/vec_i16_data.csv'
CONFIG '{"region":"us-east-1"}'
CREDENTIALS '{}'
INTO TABLE vectors_i16
FIELDS TERMINATED BY ','
ENCLOSED BY "'"
FORMAT CSV;

Start the pipeline.

START PIPELINE vec_i16_pipeline FOREGROUND;

Once the pipeline has completed, validate that the data loaded using the following SQL.

SELECT vec FROM vectors_i16;

+---------+
| vec     |
+---------+
| [1,2,3] |
| [4,5,6] |
| [1,4,8] |
+---------+

Once a pipeline is no longer needed it can be dropped.

DROP PIPELINE vec_i16_pipeline;

If you have started a pipeline in the background (by omitting the FOREGROUND keyword), you can stop the pipeline instead of, or before, dropping it. Stopping a pipeline allows the pipeline to be used later, dropping a pipeline removes the pipeline from the system. Stopping is applicable for background pipelines only. Refer to STOP PIPELINE and DROP PIPELINE for more information.

Example 3b - Loading data in JSON Format from a Local File

Use the following SQL to load the data with vectors in JSON array format into the vectors_i16 table. For this example, place the data in a local file accessible to your SingleStore client and replace '/tmp/vec_i16_data.csv' with the path to your text file.

LOAD DATA LOCAL INFILE '/tmp/vec_i16_data.csv'
INTO TABLE vectors_i16
FIELDS TERMINATED BY ','
ENCLOSED BY "'"
FORMAT CSV;

Note that lines FIELDS TERMINATED BY ',' and ENCLOSED BY "''" clause tells the database that the fields in the data file are separated by commas and that the fields may be enclosed with single quotes. This allows the database to load the data as formatted above.

Example 4a - Export Vector Data in Parquet Format

To export into a Parquet file on S3, use the following command. You will need to replace the S3 URI and the configuration and credentials with your own values. Refer to SELECT for additional details on AWS configuration and credentials in SingleStore.

SELECT id, vec:>BLOB AS vec
FROM vectors
INTO S3 's3://vec_data_folder/vec_f32_data.parquet'
CONFIG '{"region":"us-west-2"}'
CREDENTIALS '{
     "aws_access_key_id":"your_access_key_id",
     "aws_secret_access_key":"your_secret_access_key",
     "aws_session_token":"your_session_token"}'
FORMAT PARQUET;

Note that the first line of this command uses a cast, vec:>BLOB AS vec to obtain the binary representation of the VECTOR instead of the JSON array representation and to ensure that the binary representation is encoded in the Parquet file.

You can output data in Parquet format to a local file using the following command.

SELECT id, vec :>BLOB AS vec
FROM vectors
INTO outfile "/tmp/vec_f32_data.parquet"
FORMAT PARQUET;

Example 4b - Export Vector Data in Hexadecimal Format

To export the vectors table with vectors encoded in hexadecimal on S3, use the command below. Again, you will need to replace the S3 URI, configuration, and credentials with your own values.

SELECT id, HEX(vec:>BLOB) AS vec
FROM vectors
INTO S3 's3://vec_data_folder/vec_f32_data_hex.csv'
CONFIG '{"region":"us-west-2"}'
CREDENTIALS '{
     "aws_access_key_id":"your_access_key_id",
     "aws_secret_access_key":"your_secret_access_key",
     "aws_session_token":"your_session_token"}';

Observe the syntax in the first line HEX(vec:>BLOB) which converts the vector to hexadecimal. The cast vec:>BLOB is required; HEX(vec) will return the hexadecimal representation of the JSON representation of the vector, while HEX(vec:>BLOB) returns the hexadecimal representation of the binary vector data. This behavior will change in a future release and the cast to BLOB will no longer be required.

You can output the data with vectors encoded in hexadecimal to a local CSV file using the following command.

SELECT id, HEX(vec:>BLOB) AS vec
FROM vectors
INTO outfile "/tmp/vec_f32_data_hex.csv";