Data Manipulation
SurrealDB supports a number of methods for interacting with the database and performing CRUD operations.
| Method | Description |
|---|
db.Select() | Selects all records in a table, or a specific record, from the database |
db.Create() | Creates a record in the database |
db.Insert() | Inserts one or multiple records in the database |
db.InsertRelation() | Inserts one or multiple relations in the database |
db.Update() | Updates all records in a table, or a specific record, in the database |
db.Upsert() | Creates or updates a set of records in a table, or a specific record, in the database |
db.Merge() | Modifies all records in a table, or a specific record, in the database |
db.Patch() | Applies JSON Patch changes to all records, or a specific record, in the database |
db.Delete() | Deletes all records in a table, or a specific record, from the database |
.Select<T>()
Selects all records in a table, or a specific record, from the database.
Method Syntax
await db.Select<T>(resource)
Arguments
| Arguments | Description |
|---|
thing required | The table name or a RecordId to select. |
cancellationToken optional | The cancellationToken enables graceful cancellation of asynchronous operations. |
Example usage
var people = await db.Select<Person>("person");
var person = await db.Select<Person>(("person", "h5wxrf2ewk8xjxosxtyc"));
var person = await db.Select<Person>(new StringRecordId("person:h5wxrf2ewk8xjxosxtyc"));
var person = await db.Select<Person>(("person", new Guid("8424486b-85b3-4448-ac8d-5d51083391c7")));
.Create<T>()
Creates a record in the database.
Method Syntax
await db.Create<T>(resource, data)
Arguments
| Arguments | Description |
|---|
thing required | The table name or a RecordId to create. |
data optional | The document / record data to insert. |
cancellationToken optional | The cancellationToken enables graceful cancellation of asynchronous operations. |
Example usage
var person = await db.Create<Person>("person");
var person = await db.Create("person", new Person { Name = "Tobie" });
var personToCreate = new Person
{
Id = ("person", "tobie"),
Name = "Tobie",
Settings = new Settings
{
Active = true,
Marketing = true,
},
};
var result = await db.Create(personToCreate);
.Insert<T>()
Inserts one or multiple records in the database.
Method Syntax
await db.Insert<T>(table, data)
Arguments
| Arguments | Description |
|---|
table optional | Optionally pass along a table to insert into. |
data optional | Either a single document/record or an array of documents/records to insert |
cancellationToken optional | The cancellationToken enables graceful cancellation of asynchronous operations. |
Example usage
var posts = new List<Post>
{
new Post
{
Id = ("post", "First"),
Title = "An article",
Content = "This is the first article"
},
new Post
{
Id = ("post", "Second"),
Title = "An article",
Content = "This is the second article"
}
};
await db.Insert("post", posts);
.InsertRelation<T>()
Inserts one or multiple relations in the database.
Method Syntax
await db.InsertRelation<T>(table, data)
Arguments
| Arguments | Description |
|---|
table optional | Optionally pass along a table to insert into. |
data optional | Either a single document/record or an array of documents/records to insert |
cancellationToken optional | The cancellationToken enables graceful cancellation of asynchronous operations. |
Example usage
await db.InsertRelation(
new WroteRelation
{
In = ("user", "u1"),
Out = ("post", "p1"),
CreatedAt = now,
NumberOfPages = 144
}
);
.Update<T>()
Updates all records in a table, or a specific record, in the database.
Method Syntax
await db.Update<T>(thing, data)
This function replaces the current document / record data with the specified data.
Arguments
| Arguments | Description |
|---|
thing required | The table name or the specific RecordId to update. |
data optional | The document / record data to update. |
cancellationToken optional | The cancellationToken enables graceful cancellation of asynchronous operations. |
Example usage
var post = new Post
{
Id = ("post", "another"),
Title = "A new article",
Content = "This is a new article created using the .NET SDK"
};
await db.Update(post);
var data = new Person
{
Name = "Tobie",
Settings = new Settings
{
Active = true,
Marketing = true,
},
};
await db.Update("person", data);
.Upsert<T>()
Creates or updates a specific record.
Method Syntax
await db.Upsert<T>(data)
This function creates a new document / record or replaces the current one with the specified data.
Arguments
| Arguments | Description |
|---|
data required | The document / record data to insert. |
cancellationToken optional | The cancellationToken enables graceful cancellation of asynchronous operations. |
Example usage
var person = new Person
{
Id = ("person", "tobie"),
Name = "Tobie",
Settings = new Settings
{
Active = true,
Marketing = true,
},
};
var created = await db.Upsert(person);
var updated = await db.Upsert(person);
.Merge<T>()
Modifies all records in a table, or a specific record.
Method Syntax
await db.Merge<T>(resource, data)
This function merges the current document / record data with the specified data.
Arguments
| Arguments | Description |
|---|
thing required | The table name or the specific RecordId to merge. |
data optional | The data with which to modify the records. |
cancellationToken optional | The cancellationToken enables graceful cancellation of asynchronous operations. |
Example usage
Merging data within a single record
var merge = new PersonMerge
{
Id = ("person", "tobie"),
Settings = new Settings
{
Active = true,
Marketing = false,
},
};
var result = await db.Merge<PersonMerge, Person>(merge);
var data = new Dictionary<string, object>
{
{ "tags", new List<string> { "developer", "engineer" } }
};
var result = await db.Merge<Person>(("person", "tobie"), data);
Merging data for every record in a table
var merge = new PersonMerge
{
Settings = new Settings
{
Active = true,
Marketing = false,
},
};
var result = await db.Merge<PersonMerge, Person>("person", merge);
var data = new Dictionary<string, object>
{
{ "tags", new List<string> { "developer", "engineer" } }
};
var result = await db.Merge<Person>("person", data);
.Patch<T>()
Applies JSON Patch changes to all records, or a specific record, in the database.
Method Syntax
await db.Patch<T>(resource, data)
This function patches document / record data with the specified JSON Patch data.
Arguments
| Arguments | Description |
|---|
thing required | The table name or the specific RecordId to patch. |
data optional | The JSON Patch data with which to patch the records. |
cancellationToken optional | The cancellationToken enables graceful cancellation of asynchronous operations. |
Example usage
var result = await db.Patch(("person", "tobie"), patches);
var result = await db.Patch("person", patches);
.Delete()
Deletes all records in a table, or a specific record, from the database.
Method Syntax
await db.Delete(resource)
Arguments
| Arguments | Description |
|---|
thing required | The table name or a RecordId to delete. |
cancellationToken optional | The cancellationToken enables graceful cancellation of asynchronous operations. |
Example usage
await db.Delete("person");
await db.Delete(("person", "h5wxrf2ewk8xjxosxtyc"));
