Records Service - SnackBase

The Records service provides methods for creating, reading, updating, and deleting records in your SnackBase collections.

Overview

Records are the actual data stored in your collections. Each record in a collection has the same structure (schema) defined by the collection’s fields.

import { SnackBaseClient } from "@snackbase/sdk";

const client = new SnackBaseClient({
  baseUrl: "https://api.example.com",
});

// Access the records service
const records = client.records;

List Records

Get all records from a collection with pagination:

const result = await client.records.list("posts");

console.log(result.items); // Array of records
console.log(result.total); // Total count
console.log(result.skip);  // Offset
console.log(result.limit);  // Page size

With Filtering

const result = await client.records.list("posts", {
  filter: { status: "published" },
});

With Sorting

// Sort by createdAt descending (newest first)
const result = await client.records.list("posts", {
  sort: "-createdAt",
});

// Sort by multiple fields
const result = await client.records.list("posts", {
  sort: "-createdAt,title",
});

With Pagination

const result = await client.records.list("posts", {
  skip: 0,
  limit: 20,
});

With Field Selection

const result = await client.records.list("posts", {
  fields: ["id", "title", "createdAt"],
});

Combined Example

const result = await client.records.list("posts", {
  filter: { status: "published" },
  sort: "-createdAt",
  skip: 0,
  limit: 20,
  fields: ["id", "title", "author", "createdAt"],
});

Get a Single Record

Retrieve a specific record by ID:

const post = await client.records.get("posts", "record-id");

console.log(post.id);
console.log(post.title);
console.log(post.content);

With Field Selection

const post = await client.records.get("posts", "record-id", {
  fields: ["id", "title"],
});

const post = await client.records.get("posts", "record-id", {
  expand: ["author", "comments"],
});

Create a Record

Create a new record in a collection:

const newPost = await client.records.create("posts", {
  title: "My First Post",
  content: "This is the content of my post.",
  status: "published",
  views: 0,
});

console.log("Created:", newPost.id);

The id, createdAt, and updatedAt fields are automatically generated by SnackBase.

Update a Record

Full Update (PUT)

Replace all fields of a record:

const updated = await client.records.update("posts", "record-id", {
  title: "Updated Title",
  content: "Updated content",
  status: "published",
  views: 10,
});

Using update() replaces all fields. Fields not included will be set to null (unless they have default values).

Partial Update (PATCH)

Update only specific fields:

const patched = await client.records.patch("posts", "record-id", {
  views: 15,
});

Use patch() for most updates to avoid accidentally clearing fields.

Delete a Record

Remove a record from a collection:

await client.records.delete("posts", "record-id");

console.log("Record deleted");

Using the Query Builder

For complex queries, use the fluent query builder:

const results = await client.records
  .query("posts")
  .select("id", "title", "author.name")
  .expand("author", "comments")
  .filter("status", "=", "published")
  .filter("createdAt", ">=", "2024-01-01")
  .sort("createdAt", "desc")
  .page(1, 20)
  .get();

console.log(results.items);

See the Query Builder guide for more details.

TypeScript Support

Use TypeScript for type-safe record operations:

interface Post {
  id: string;
  title: string;
  content: string;
  status: "draft" | "published" | "archived";
  views: number;
  createdAt: string;
  updatedAt: string;
}

// Create with type safety
const newPost = await client.records.create("posts", {
  title: "My Post",
  content: "Content",
  status: "published",
  views: 0,
});

// Get with type safety
const post = await client.records.get("posts", "record-id");

// List with type safety
const result = await client.records.list("posts");

Batch Operations

Create Multiple Records

const records = await Promise.all([
  client.records.create("posts", { title: "Post 1", content: "Content 1" }),
  client.records.create("posts", { title: "Post 2", content: "Content 2" }),
  client.records.create("posts", { title: "Post 3", content: "Content 3" }),
]);

Update Multiple Records

const updates = [
  { id: "id1", data: { status: "published" } },
  { id: "id2", data: { status: "published" } },
  { id: "id3", data: { status: "published" } },
];

await Promise.all(
  updates.map(({ id, data }) =>
    client.records.patch("posts", id, data)
  )
);

Real-Time Updates

Combine with the real-time service for live updates:

// Subscribe to collection changes
await client.realtime.connect();
await client.realtime.subscribe("posts");

client.realtime.on("posts.create", (data) => {
  console.log("New post created:", data);
  // Refresh your local data
});

client.realtime.on("posts.update", (data) => {
  console.log("Post updated:", data);
  // Update your local data
});

client.realtime.on("posts.delete", (data) => {
  console.log("Post deleted:", data);
  // Remove from your local data
});

Error Handling

import {
  NotFoundError,
  ValidationError,
  AuthenticationError,
} from "@snackbase/sdk";

try {
  const post = await client.records.get("posts", "non-existent-id");
} catch (error) {
  if (error instanceof NotFoundError) {
    console.error("Record not found");
  } else if (error instanceof ValidationError) {
    console.error("Validation error:", error.fields);
  } else if (error instanceof AuthenticationError) {
    console.error("Authentication required");
  } else {
    console.error("Unknown error:", error);
  }
}

Reference

`list(collection, params?)`

List records from a collection. Parameters:

collection (string) - Collection name
params (object) - Query parameters
- filter (object) - Filter expression
- sort (string) - Sort expression
- skip (number) - Records to skip
- limit (number) - Max records to return
- fields (string[]) - Fields to return
- expand (string[]) - Relations to expand

Returns: Promise<RecordListResponse>

`get(collection, recordId, params?)`

Get a single record by ID. Parameters:

collection (string) - Collection name
recordId (string) - Record ID
params (object) - Query parameters
- fields (string[]) - Fields to return
- expand (string[]) - Relations to expand

Returns: Promise<any & BaseRecord>

`create(collection, data)`

Create a new record. Parameters:

collection (string) - Collection name
data (object) - Record data

Returns: Promise<any & BaseRecord>

`update(collection, recordId, data)`

Full update of a record (PUT). Parameters:

collection (string) - Collection name
recordId (string) - Record ID
data (object) - Complete record data

Returns: Promise<any & BaseRecord>

`patch(collection, recordId, data)`

Partial update of a record (PATCH). Parameters:

collection (string) - Collection name
recordId (string) - Record ID
data (object) - Fields to update

Returns: Promise<any & BaseRecord>

`delete(collection, recordId)`

Delete a record. Parameters:

collection (string) - Collection name
recordId (string) - Record ID

Returns: Promise<{ success: boolean }>

`query(collection)`

Create a query builder for the collection. Parameters:

collection (string) - Collection name

Returns: QueryBuilder

Batch Operations

Perform multiple record operations atomically using the dedicated batch endpoint:

// Batch create
const created = await client.records.batchCreate("posts", [
  { title: "Post 1", status: "draft" },
  { title: "Post 2", status: "published" },
]);

// Batch update
const updated = await client.records.batchUpdate("posts", [
  { id: "post-1", data: { status: "published" } },
  { id: "post-2", data: { status: "archived" } },
]);

// Batch delete
await client.records.batchDelete("posts", ["post-1", "post-2"]);

Aggregation Queries

Run server-side aggregations without fetching raw records:

const result = await client.records.aggregate("orders", {
  function: "sum",
  field: "total",
  filter: "status = 'completed'",
  group_by: "category",
});

Supported functions: count, sum, avg, min, max.

Reference Expansion

Expand reference fields inline to avoid N+1 queries:

const orders = await client.records.list("orders", {
  expand: "customer_id,product_id",
});

// Each order now includes the full referenced records
console.log(orders.items[0].expand.customer_id.name);

Next Steps

Query Builder - Advanced querying
Collections - Manage collections
Realtime - Real-time subscriptions

​Overview

​List Records

​With Filtering

​With Sorting

​With Pagination

​With Field Selection

​Combined Example

​Get a Single Record

​With Field Selection

​With Related Records

​Create a Record

​Update a Record

​Full Update (PUT)

​Partial Update (PATCH)

​Delete a Record

​Using the Query Builder

​TypeScript Support

​Batch Operations

​Create Multiple Records

​Update Multiple Records

​Real-Time Updates

​Error Handling

​Reference

​list(collection, params?)

​get(collection, recordId, params?)

​create(collection, data)

​update(collection, recordId, data)

​patch(collection, recordId, data)

​delete(collection, recordId)

​query(collection)

​Batch Operations

​Aggregation Queries

​Reference Expansion

​Next Steps

Overview

List Records

With Filtering

With Sorting

With Pagination

With Field Selection

Combined Example

Get a Single Record

With Field Selection

With Related Records

Create a Record

Update a Record

Full Update (PUT)

Partial Update (PATCH)

Delete a Record

Using the Query Builder

TypeScript Support

Batch Operations

Create Multiple Records

Update Multiple Records

Real-Time Updates

Error Handling

Reference

`list(collection, params?)`

`get(collection, recordId, params?)`

`create(collection, data)`

`update(collection, recordId, data)`

`patch(collection, recordId, data)`

`delete(collection, recordId)`

`query(collection)`

Batch Operations

Aggregation Queries

Reference Expansion

Next Steps