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.

SET vector_type_project_format = JSON;  /* to make vector output readable */

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.

SET vector_type_project_format = JSON;  /* to make vector output readable */

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

SET vector_type_project_format = JSON;  /* to make vector output readable */

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

SET vector_type_project_format = JSON;  /* to make vector output readable */

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 4a - Export Vector Data in Parquet Format

When exporting vector data in Parquet, or other binary format, set vector_type_project_format to BINARY.

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.

SET vector_type_project_format = BINARY;

SELECT id, 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;

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) 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"}';