Data Querying

The methods below are used to interact with the database and perform CRUD operations. You can also use the query method to run SurrealQL statements against the database.

.query()

Runs a set of SurrealQL statements against the database.

Method Syntax
async db.query<T>(query, vars)

Arguments

Example usage

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

// Assign the variable on the connection
const result = await db.query<[Person[], Person[]]>(
	'CREATE person SET name = "John"; SELECT * FROM type::table($tb);',
	{ tb: 'person' }
);

// Get the first result from the first query
const created = result[0].result[0];

// Get all of the results from the second query
const people = result[1].result;

.query_raw()

With .query_raw(), you will get back the raw RPC response. This contrast to the .query() method, this will not throw for errors that occur in individual queries, but will rather give those back as a string, and this will include the time it took to execute the individual queries.

Built-in methods

The JavaScript SDK also provides easy to use methods for data selection and altering.

Table vs RecordId

These methods all accept either a Table vs RecordId vs StringRecordId, or a “thing”, as their first argument. Passing a Table instance, or a string, will make the method return an array of objects of generic type T. If you instead pass a RecordId or StringRecordId instance, the method will return a single object of generic type T back.

.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<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;