table.insert()

DOCS • API • Table API

---

Programmatically perform an INSERT query.

See related ➞ INSERT

Syntax

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

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

table.insert(
    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 manipulation.

└ 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 | Array<object> | 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: '[email protected]'}
);

Multi-entry insert:

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

Columns/values insert:

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

Returning records

Return the just created record (object):

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

Return the just created records (array):

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

Multi-dimensional insert

See also ➞ Magic Paths

Insert a multi-dimensional record:

// Structured multi-dimensional INSERT | MANY-TO-ONE
// DESC: for each book entry CREATED, CREATE a user with specified name and email, RETURNING entire tree
const result = await table.insert(
    [ 'title', 'content', { path: ['author', { columns: ['name', 'email'] }]} ],
    [
        ['Beauty and the Beast', '(C) 2024 [email protected]\nBeauty and the Beast...', [
            'John Doe',
            '[email protected]'
        ]],
        ['The Secrets of Midnight Garden', '(C) 2024 [email protected]\nThe Secrets of Midnight Garden...', [
            'Alice Blue',
            '[email protected]'
        ]]
    ],
    { returning: ['*'] }
);

See ➞ Magic Paths ➞ Example 7