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 Syntaxasync db.query<T>(query, vars)
Arguments
| Arguments | Description | ||
|---|---|---|---|
query | Specifies the SurrealQL statements. | ||
vars | Assigns variables which can be used in the query. |
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 Syntaxasync db.select<T>(thing)
Arguments
| Arguments | Description | ||
|---|---|---|---|
thing | The table name or a |
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 Syntaxasync db.create<T>(thing, data)
Arguments
| Arguments | Description | ||
|---|---|---|---|
thing | The table name or a | ||
data | The document / record data to create. |
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 Syntaxasync db.insert<T>(thing, data)
Arguments
| Arguments | Description | ||
|---|---|---|---|
thing | The table name or | ||
data | Either a single document/record or an array of documents/records to insert |
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,
},
});
const person = await db.insert<Person>(new RecordId('person', 'tobie'), {
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 $thing $data;
.update()
Updates all records in a table, or a specific record, in the database.
Method Syntaxasync db.update<T>(thing, data)
NOTE: This function replaces the current document / record data with the specified data.
Arguments
| Arguments | Description | ||
|---|---|---|---|
thing | The table name or the specific | ||
data | The document / record data to update. |
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 Syntaxasync db.merge<T>(thing, data)
NOTE: This function merges the current document / record data with the specified data.
Arguments
| Arguments | Description | ||
|---|---|---|---|
thing | The table name or the specific | ||
data | The document / record data to merge. |
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 Syntaxasync db.patch(thing, data)
NOTE: This function patches the current document / record data with the specified JSON Patch data.
Arguments
| Arguments | Description | ||
|---|---|---|---|
thing | The table name or the specific | ||
data | The JSON Patch data with which to patch the records. |
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 Syntaxasync db.delete<T>(thing)
Arguments
| Arguments | Description | ||
|---|---|---|---|
thing | The table name or a |
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;