InsertQueryOptions

Defined in: define/table/types/query.ts:309

Defines the options available for an INSERT query.

Example

// Single insert
const user = await User.insert({
  data: { name: 'John', email: 'john@example.com' },
});

// Bulk insert
const users = await User.insert({
  data: [
    { name: 'John', email: 'john@example.com' },
    { name: 'Jane', email: 'jane@example.com' },
  ],
});

// With IGNORE (skip duplicates silently)
const users = await User.insert({
  data: { name: 'John', email: 'john@example.com' },
  ignore: true,
});

// With ON DUPLICATE KEY UPDATE
const users = await User.insert({
  data: { name: 'John', email: 'john@example.com' },
  onDuplicate: surql`visits += 1`,
});

// With custom RETURN clause
const names = await User.insert({
  data: { name: 'John', email: 'john@example.com' },
  return: { value: 'name' },
});

Type Parameters

TTable

TTable

The data shape of the table being inserted into.

TData

TData = TTable | TTable[]

The type of data to insert (single object or array).

Properties

data

data: TData extends unknown[] ? TData<TData>[number] & object[] : TData & object

Defined in: define/table/types/query.ts:329

The data to insert. Can be a single object or an array of objects. Optionally includes an id field for specifying custom record IDs.

Example

// Single record
{ data: { name: 'John', email: 'john@example.com' } }

// With custom ID
{ data: { id: 'user:john', name: 'John', email: 'john@example.com' } }

// Multiple records
{ data: [
  { name: 'John', email: 'john@example.com' },
  { name: 'Jane', email: 'jane@example.com' },
]}

---

ignore?

optional ignore: boolean

Defined in: define/table/types/query.ts:352

If true, silently ignores duplicate record IDs instead of throwing an error. Equivalent to INSERT IGNORE INTO.

Example

// Will not throw error if user:123 already exists
await User.insert({
  data: { id: 'user:123', name: 'John' },
  ignore: true,
});

---

onDuplicate?

optional onDuplicate: BoundQuery<unknown[]> | Expr | Partial<TTable>

Defined in: define/table/types/query.ts:400

Specifies how to update existing records when a duplicate ID or unique index violation occurs. Can be:

• Object: { field: value } pairs to update
• BoundQuery: Raw SurrealQL for complex updates

Use $input.field to reference the attempted insert data.

Example

// Simple field updates
await User.insert({
  data: { name: 'John', email: 'john@example.com' },
  onDuplicate: { updatedAt: new Date() },
});

// Increment/decrement with raw query
await User.insert({
  data: { name: 'John', email: 'john@example.com' },
  onDuplicate: surql`visits += 1, lastSeen = time::now()`,
});

// Reference input data
await User.insert({
  data: { name: 'John', email: 'john@example.com' },
  onDuplicate: surql`name = $input.name, updatedAt = time::now()`,
});

---

relation?

optional relation: boolean

Defined in: define/table/types/query.ts:337

If true, uses INSERT RELATION syntax for relation tables. Automatically set for relation tables defined with Table.relation().

---

return?

optional return: ReturnType

Defined in: define/table/types/query.ts:369

Specifies what to return from the INSERT operation.

Example

// Return nothing
await User.insert({ data, return: 'NONE' });

// Return specific fields
await User.insert({ data, return: ['id', 'name'] });

// Return single field value
const names = await User.insert({ data, return: { value: 'name' } });