Data manipulation

SurrealDB supports a number of methods for interacting with the database and performing CRUD operations.

.select()

Selects all records in a table, or a specific record, from the database.

Method Syntax
async db.select<T>(thing)

Arguments

Example usage

type Person = {
	id: string;
	name: string;
};

// Select all records from a table
const people = await db.select<Person>('person');

// Select a specific record from a table
const person = await db.select<Person>(new RecordId('person', 'h5wxrf2ewk8xjxosxtyc'));
const person = await db.select<Person>(new StringRecordId('person:h5wxrf2ewk8xjxosxtyc'));

Translated query

This function will run the following query in the database.

SELECT * FROM $thing;

.create()

Creates a record in the database.

Method Syntax
async db.create<T>(thing, data)

Arguments

Example usage

type Person = {
	id: string;
	name: string;
	settings: {
		active: boolean;
		marketing: boolean;
	};
};

// Create a record with a random ID
const [person] = await db.create<Person>('person');

// Create a record with a specific ID
const person = await db.create<Person>(new RecordId('person', 'tobie'), {
	name: 'Tobie',
	settings: {
		active: true,
		marketing: true,
	},
});

// The content you are creating the record with might differ from the return type
const [record] = await db.create<
	Person,
	Pick<Person, 'name'>
>(
    new RecordId('person', 'tobie'),
    {
        name: 'Tobie',
    }
);

Translated query

This function will run the following query in the database.

CREATE $thing CONTENT $data;

.insert()

Inserts one or multiple records in the database.

Method Syntax
async db.insert<T>(table, data)

Arguments

Example usage

type Person = {
	id: string;
	name: string;
	settings: {
		active: boolean;
		marketing: boolean;
	};
};

// Insert a single record
const [person] = await db.insert<Person>('person', {
	name: 'Tobie',
	settings: {
		active: true,
		marketing: true,
	},
});

// Insert multiple records
const people = await db.insert<Person>('person', [
	{
		name: 'Tobie',
		settings: {
			active: true,
			marketing: true,
		},
	},
	{
		name: 'Jaime',
		settings: {
			active: true,
			marketing: true,
		},
	},
]);

// The content you are creating the record with might differ from the return type
const people = await db.insert<
	Person,
	Pick<Person, 'name'>
>('person', [
	{ name: 'Tobie' },
	{ name: 'Jaime' },
]);

Translated query

This function will run the following query in the database.

INSERT INTO $table $data;

.insert_relation()

Inserts one or multiple relations in the database.

Method Syntax
async db.insert_relation<T>(table, data)

Arguments

Example usage

type Likes = {
	id: RecordId<"likes">;
	in: RecordId<"person">;
	out: RecordId<"post">;
};

// Insert a single record
const [person] = await db.insert_relation<Likes>('likes', {
	in: new RecordId('person', 'tobie'),
	out: new RecordId('post', 123),
});

// Insert multiple records across tables
const people = await db.insert<Likes>('likes', [
	{
    	in: new RecordId('person', 'tobie'),
    	out: new RecordId('post', 123),
	},
	{
    	in: new RecordId('person', 'jaime'),
    	out: new RecordId('post', 456),
	},
]);

Translated query

This function will run the following query in the database.

INSERT RELATION INTO $table $data;

.update()

Updates all records in a table, or a specific record, in the database.

Method Syntax
async db.update<T>(thing, data)

Note

This function replaces the current document / record data with the specified data.

Arguments

Example usage

type Person = {
	id: string;
	name: string;
	settings: {
		active: boolean;
		marketing: boolean;
	};
};

// Update all records in a table
const people = await db.update<Person>('person');

// Update a record with a specific ID
const person = await db.update<Person>(new RecordId('person', 'tobie'), {
	name: 'Tobie',
	settings: {
		active: true,
		marketing: true,
	},
});

// The content you are updating the record with might differ from the return type
const record = await db.update<
	Person,
	Pick<Person, 'name'>
>(new RecordId('person', 'tobie'), {
	name: 'Tobie',
});

Translated query

This function will run the following query in the database.

UPDATE $thing CONTENT $data;

.merge()

Modifies all records in a table, or a specific record, in the database.

Method Syntax
async db.merge<T>(thing, data)

Note

This function merges the current document / record data with the specified data.

Arguments

Example usage

type Person = {
	id: string;
	name: string;
	updated_at: Date;
	settings: {
		active: boolean;
		marketing: boolean;
	};
};

// Update all records in a table
const people = await db.merge<Person>('person', {
	updated_at: new Date(),
});

// Update a record with a specific ID
const person = await db.merge<Person>(new RecordId('person', 'tobie'), {
	updated_at: new Date(),
	settings: {
		active: true,
	},
});

// The content you are merging the record with might differ from the return type
const record = await db.merge<
	Person,
	Pick<Person, 'name'>
>(new RecordId('person', 'tobie'), {
	name: 'Tobie',
});

Translated query

This function will run the following query in the database.

UPDATE $thing MERGE $data;

.patch()

Applies JSON Patch changes to all records, or a specific record, in the database.

Method Syntax
async db.patch(thing, data)

Note

This function patches the current document / record data with the specified JSON Patch data.

Arguments

Example usage

// Update all records in a table
const people = await db.patch('person', [
	{ op: 'replace', path: '/created_at', value: new Date() },
]);

// Update a record with a specific ID
const person = await db.patch(new RecordId('person', 'tobie'), [
	{ op: 'replace', path: '/settings/active', value: false },
	{ op: 'add', path: '/tags', value: ['developer', 'engineer'] },
	{ op: 'remove', path: '/temp' },
]);

Translated query

This function will run the following query in the database.

UPDATE $thing PATCH $data;

.delete()

Deletes all records in a table, or a specific record, from the database.

Method Syntax
async db.delete<T>(thing)

Arguments

Example usage

// Delete all records from a table
await db.delete('person');

// Delete a specific record from a table
await db.delete(new RecordId('person', 'h5wxrf2ewk8xjxosxtyc'));

Translated query

This function will run the following query in the database.

DELETE $thing;