Data Manipulation

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

.Select<T>()

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

Method Syntax
await db.Select<T>(resource)

Arguments

Example usage

// Select all records from a table
var people = await db.Select<Person>("person");

// Select a specific record from a table
var person = await db.Select<Person>(("person", "h5wxrf2ewk8xjxosxtyc"));
var person = await db.Select<Person>(new StringRecordId("person:h5wxrf2ewk8xjxosxtyc"));

// Select a specific record from a table, given a non-string id
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

Example usage

// Create a record with a random ID
var person = await db.Create<Person>("person");

// Create a record with a random ID & specific fields
var person = await db.Create("person", new Person { Name = "Tobie" });

// Create a record with a specific ID
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

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

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)

Note

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

Arguments

Example usage

var post = new Post
{
    Id = ("post", "another"),
    Title = "A new article",
    Content = "This is a new article created using the .NET SDK"
};

// Updates a single record
await db.Update(post);

var data = new Person
{
    Name = "Tobie",
    Settings = new Settings
    {
        Active = true,
        Marketing = true,
    },
};

// Updates all records inside the "person" table
await db.Update("person", data);

.Upsert<T>()

Creates or updates a specific record.

Method Syntax
await db.Upsert<T>(data)

Note

This function creates a new document / record or replaces the current one with the specified data.

Arguments

Example usage

var person = new Person
{
    Id = ("person", "tobie"), // Id is mandatory to apply create or update
    Name = "Tobie",
    Settings = new Settings
    {
        Active = true,
        Marketing = true,
    },
};

// Create a new record when it doesn't exist
var created = await db.Upsert(person);

// Update an existing record when it does exist
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)

Note

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

Arguments

Example usage

Merging data within a single record
// Only changes the fields specified in the merge object
var merge = new PersonMerge
{
    Id = ("person", "tobie"),
    Settings = new Settings
    {
        Active = true,
        Marketing = false,
    },
};
var result = await db.Merge<PersonMerge, Person>(merge);

// Only changes the fields specified in the Dictionary
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
// Only changes the fields specified in the merge object
var merge = new PersonMerge
{
    Settings = new Settings
    {
        Active = true,
        Marketing = false,
    },
};
var result = await db.Merge<PersonMerge, Person>("person", merge);

// Only changes the fields specified in the Dictionary
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)

Note

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

Arguments

Example usage

// Update a record with a specific ID
var result = await db.Patch(("person", "tobie"), patches);

// Update all records in a table
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

Example usage

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

// Delete a specific record from a table
await db.Delete(("person", "h5wxrf2ewk8xjxosxtyc"));