Insert rows (Go)
Inserts multiple rows into a table.
This method can insert a row in an existing CQL table, but the Data API does not support all CQL data types or modifiers. For more information, see Data type compatibility in tables (Go).
For general information about working with tables and rows, see About tables with the Data API (Go).
|
Ready to write code? See the examples for this method to get started. If you are new to the Data API, check out the quickstart. |
Result
Inserts the specified rows and returns an *InsertManyResult struct that includes the primary keys of the inserted rows.
If a row with the specified primary key already exists in the table, the row is overwritten with the specified column values. Unspecified columns remain unchanged.
If a row fails to insert and the insertions are sequential (SetOrdered(true)), then that row and all subsequent rows are not inserted.
The resulting error message indicates the first row that failed to insert.
If a row fails to insert and the insertions are not sequential (SetOrdered(false)), the operation will try to insert the remaining rows and then throw an error.
The error indicates which rows were successfully inserted and the problems with the failed rows.
Parameters
Use the InsertMany method, which belongs to the Table type.
Method signature
func (t *Table) InsertMany(
ctx context.Context,
rows any,
opts ...options.TableInsertManyOption
) (*results.InsertManyResult, error)| Name | Type | Summary |
|---|---|---|
|
|
The context for the operation. |
|
|
A non-empty slice of structs or maps, with each struct or map describing a row to insert. All primary key values are required. To reduce tombstones, you should not explicitly set a column to The table definition determines the columns in the row, the type for each column, and the primary key. To get this information, see List table metadata (Go). |
|
Optional.
A builder to generate options for this operation.
See Methods of the |
| Method | Summary |
|---|---|
|
Whether to insert the rows sequentially. If false, the rows are inserted in an arbitrary order with possible concurrency. This results in a much higher insert throughput than an equivalent ordered insertion. Default: false |
|
The number of rows to insert in a single API request. DataStax recommends that you leave this unspecified to use the system default. |
|
The maximum number of concurrent requests to the API at a given time. For ordered insertions, must be 1 or unspecified. Default: |
|
Optional. General API options for this operation, including the timeout. |
Examples
The following examples demonstrate how to insert multiple rows into a table.
Insert rows
When you insert rows, you must specify a non-null value for each primary key column for each row.
Non-primary key columns are optional.
To reduce tombstones, you should not explicitly set a column to null.
package main
import (
"context"
"log"
"github.com/datastax/astra-db-go/v2/astra"
"github.com/datastax/astra-db-go/v2/astra/datatypes"
"github.com/datastax/astra-db-go/v2/astra/options"
)
func main() {
ctx := context.Background()
// Get an existing table
client := astra.NewClient()
database := client.Database(
"API_ENDPOINT",
options.API().SetToken("APPLICATION_TOKEN"),
)
table := database.Table("TABLE_NAME")
// Insert rows into the table
_, err := table.InsertMany(
ctx,
[]map[string]any{
{
"title": "Computed Wilderness",
"author": "Ryan Eau",
"number_of_pages": 432,
"due_date": datatypes.DateOnly{
Year: 2024,
Month: 12,
Day: 18},
"genres": []string{"History", "Biography"},
},
{
"title": "Desert Peace",
"author": "Walter Dray",
"number_of_pages": 355,
"rating": 4.5,
},
},
)
if err != nil {
log.Fatal(err)
}
}Insert rows with vector embeddings
You can only insert vector embeddings into vector columns.
To create a table with a vector column, see Create a table (Go). To add a vector column to an existing table, see Alter a table (Go).
All embeddings in the column should use the same provider, model, and dimensions. Mismatched embeddings can cause inaccurate vector searches.
You can use the datatypes.Vector struct to binary-encode your vector embeddings.
DataStax recommends that you always use the datatypes.Vector struct instead of a slice of floats to improve performance.
package main
import (
"context"
"log"
"github.com/datastax/astra-db-go/v2/astra"
"github.com/datastax/astra-db-go/v2/astra/datatypes"
"github.com/datastax/astra-db-go/v2/astra/options"
)
func main() {
ctx := context.Background()
// Get an existing table
client := astra.NewClient()
database := client.Database(
"API_ENDPOINT",
options.API().SetToken("APPLICATION_TOKEN"),
)
table := database.Table("TABLE_NAME")
// Insert rows into the table
_, err := table.InsertMany(
ctx,
[]map[string]any{
{
"title": "Computed Wilderness",
"author": "Ryan Eau",
"summary_genres_vector": datatypes.NewVector(
[]float32{0.08, -0.62, 0.39},
),
},
{
"title": "Desert Peace",
"author": "Walter Dray",
"summary_genres_vector": datatypes.NewVector(
[]float32{0.12, 0.53, 0.32},
),
},
},
)
if err != nil {
log.Fatal(err)
}
}Insert rows and generate vector embeddings
To automatically generate vector embeddings, your table must have a vector column with an embedding provider integration. You can configure embedding provider integrations when you create a table, add a vector column to an existing table, or alter an existing vector column.
When you insert a row, you can pass a string to the vector column. Astra DB uses the embedding provider integration to generate vector embeddings from that string.
The strings used to generate the vector embeddings are not stored. If you want to store the original strings, you must store them in a separate column.
In the following examples, summary_genres_vector is a vector column that has an embedding provider integration configured, and summary_genres_original_text is a text column to store the original text.
package main
import (
"context"
"log"
"github.com/datastax/astra-db-go/v2/astra"
"github.com/datastax/astra-db-go/v2/astra/options"
)
func main() {
ctx := context.Background()
// Get an existing table
client := astra.NewClient()
database := client.Database(
"API_ENDPOINT",
options.API().SetToken("APPLICATION_TOKEN"),
)
table := database.Table("TABLE_NAME")
// Insert rows into the table
_, err := table.InsertMany(
ctx,
[]map[string]any{
{
"title": "Computed Wilderness",
"author": "Ryan Eau",
"summary_genres_vector": "Text to vectorize",
"summary_genres_original_text": "Text to vectorize",
},
{
"title": "Desert Peace",
"author": "Walter Dray",
"summary_genres_vector": "Text to vectorize",
"summary_genres_original_text": "Text to vectorize",
},
},
)
if err != nil {
log.Fatal(err)
}
}Insert rows with a map column that uses non-string keys
package main
import (
"context"
"log"
"github.com/datastax/astra-db-go/v2/astra"
"github.com/datastax/astra-db-go/v2/astra/options"
)
func main() {
ctx := context.Background()
// Get an existing table
client := astra.NewClient()
database := client.Database(
"API_ENDPOINT",
options.API().SetToken("APPLICATION_TOKEN"),
)
table := database.Table("TABLE_NAME")
// Insert rows into the table
_, err := table.InsertMany(
ctx,
[]map[string]any{
{
// This map has non-string keys,
// so the insertion is an array of key-value pairs
"map_column_int_str": [][]any{
{1, "value1"},
{2, "value2"},
},
// This map does not have non-string keys,
// so the insertion does not need to be an array of
// key-value pairs
"map_column_str_str": map[string]any{
"key1": "value1",
"key2": "value2",
},
"title": "Once in a Living Memory",
"author": "Kayla McMaster",
},
},
)
if err != nil {
log.Fatal(err)
}
}Insert rows and specify insertion behavior
package main
import (
"context"
"log"
"github.com/datastax/astra-db-go/v2/astra"
"github.com/datastax/astra-db-go/v2/astra/datatypes"
"github.com/datastax/astra-db-go/v2/astra/options"
)
func main() {
ctx := context.Background()
// Get an existing table
client := astra.NewClient()
database := client.Database(
"API_ENDPOINT",
options.API().SetToken("APPLICATION_TOKEN"),
)
table := database.Table("TABLE_NAME")
// Insert rows into the table
_, err := table.InsertMany(
ctx,
[]map[string]any{
{
"title": "Computed Wilderness",
"author": "Ryan Eau",
"number_of_pages": 432,
"due_date": datatypes.DateOnly{
Year: 2024,
Month: 12,
Day: 18},
"genres": []string{"History", "Biography"},
},
{
"title": "Desert Peace",
"author": "Walter Dray",
"number_of_pages": 355,
"rating": 4.5,
},
},
options.TableInsertMany().
SetChunkSize(2).
SetConcurrency(2).
SetOrdered(false),
)
if err != nil {
log.Fatal(err)
}
}Client reference
For more information, see the client reference.
