table.insert()

DOCS • API • Table API

---

Programmatically perform an INSERT query.

See also ➞ INSERT

Syntax

table.select(
    entry: Entry,
    modifiers?: InsertOptions | Callback,
): Promise<InsertResult>;

table.select(
    entries: Entry[],
    modifiers?: InsertOptions | Callback,
): Promise<InsertResult>;

table.select(
    columns: Column[],
    valueMatrix: any[][],
    modifiers?: InsertOptions | Callback,
): Promise<InsertResult>;

Param	Interfaces	Description
entry	Entry	A key/value data object.
entries	Entry	An array of data objects.
columns	Column	An array of columns.
valueMatrix	-	A two-dimensional array of values; i.e. an array of values to a row.
modifiers?	InsertOptions	Optional additional query modifiers. Can be Callback—a callback function that recieves the underlying InsertStatement instance for building.

└ InsertOptions

interface InsertOptions {
    returning?: Field[];
}

Param	Interfaces	Description
returning?	Field	Optional list of fields to return from the just created records.

└ InsertResult

type InsertResult = number | object | Array<object>;

Type	Interfaces	Description
number	-	The default insert result—a number indicating the number of records created.
object	-	The insert result of the first call pattern in combination with a RETURNING clause—an object representing the created record.
Array<object>	-	The insert result of the second and third call patterns in combination with a RETURNING clause—an array of objects representing the created records.

Usage

Call Patterns

Single-entry insert:

// Single object as payload
await table.insert({ first_name: 'John', last_name: 'Doe', email: 'johndoe@example.com'});

Multi-entry insert:

// Multiple objects as payload
await table.insert([
    { first_name: 'John', last_name: 'Doe', email: 'johndoe@example.com'},
    { first_name: 'James', last_name: 'Clerk', email: 'jamesclerk@example.com'},
]);

Columns-values insert:

// Columns list and values passed distinctly
await table.insert(
    ['first_name', 'last_name', 'email'],
    [
        ['John', 'Doe', 'johndoe@example.com'],
        ['James', 'Clerk', 'jamesclerk@example.com'],
    ]
);

Returning Records

Return the just created record (object):

// ...limited to just the "id" column
const insertedRows = await table.insert(
    { first_name: 'John', last_name: 'Doe', email: 'johndoe@example.com'},
    { returning: ['id'] }
);

Return the just created records (array):

// ...limited to just the "id" column per record
const insertedRows = await table.insert(
    [
        { first_name: 'John', last_name: 'Doe', email: 'johndoe@example.com'}
    ],
    { returning: ['id'] }
);