Collection reference

A collection reference enables access to a collection of documents (NoSQL) or a table (SQL) in a database.

Why Use Collection References

You need a starting point for reading, writing, and querying data. A collection reference connects your client code to a specific collection or table, providing type-safe access to all database operations through a single entry point.

Client code

// One line to connect to your data
const users = squid.collection<User>('users');

// Then query, insert, delete, or join
const activeUsers = await users.query().eq('status', 'active').snapshot();

Collection basics

A collection reference is a typed pointer to a specific collection or table in a database. It serves as the starting point for all data operations in the Squid Client SDK.

To create a collection reference, call the collection method on the squid object with the collection name and an optional generic type parameter for type safety:

Client code

const usersCollection = squid.collection<User>('users');

To access a table in an external database, pass the connector ID as the second parameter. Find your connector ID in the connectors section of the Squid Console:

Client code

const usersCollection = squid.collection<User>('users', 'YOUR_CONNECTOR_ID');

Generic typing

Collection references accept a generic type parameter T that represents the shape of documents in the collection. This provides compile-time type safety across all operations:

Client code

interface Product {
  id: string;
  name: string;
  price: number;
  inStock: boolean;
}

// Type-safe: field names and values are checked at compile time
const products = squid.collection<Product>('products');

Reference ID

Each collection reference instance has a unique refId property that identifies it:

Client code

usersCollection.refId; // Unique identifier string

Quick Start

Step 1: Define your data type

Client code

interface User {
  id: string;
  name: string;
  email: string;
  age: number;
}

Step 2: Create a collection reference

Client code

const usersCollection = squid.collection<User>('users');

Step 3: Query and use data

Client code

// Get a snapshot of all users
const users = await usersCollection.query().snapshot();

// Access data from each document reference
for (const userRef of users) {
  console.log(userRef.data.name, userRef.data.email);
}

Available operations

Once you have a collection reference, you can use it to access documents, build queries, and perform bulk operations:

Operation	Method	Details
Get a document reference	collection.doc(id)	Document references, Document IDs
Query documents	collection.query()	Queries
Join across collections	collection.joinQuery()	Joining data across collections
Combine queries with OR	collection.or(query1, query2)	OR queries
Insert multiple documents	collection.insertMany()	Adding data
Delete multiple documents	collection.deleteMany()	Deleting data
Project specific fields	query.projectFields()	Field projection

Error Handling

Error	Cause	Solution
Collection not found	The collection name does not match any existing collection or table	Verify the collection name in the Squid Console
Invalid connector ID	The connector ID passed as the second parameter does not exist	Check the connector ID in the connectors section of the Squid Console
Type mismatch at runtime	The generic type parameter does not match the actual document shape	Ensure your TypeScript interface matches the collection schema

Best Practices

1. Always use a generic type parameter to get compile-time type safety on all operations:

   Client code

   // Recommended: typed collection
   const users = squid.collection<User>('users');
   
   // Avoid: untyped collection loses type checking on queries and mutations
   const users = squid.collection('users');

2. Reuse collection references across your component or module rather than creating new ones for each operation.

3. Store connector IDs in constants to avoid typos and simplify connector changes:

   Client code

   const POSTGRES_CONNECTOR = 'my_postgres_connector';
   const orders = squid.collection<Order>('orders', POSTGRES_CONNECTOR);

See also

• Document IDs - Document ID formats for built-in and external databases
• Document references - Read and write individual documents
• Queries - Build queries with filters, sorting, joins, and pagination
• Field projection - Optimize queries by selecting specific fields
• Adding data - Insert and update data
• Deleting data - Delete documents
• Transactions - Atomic multi-document operations
• Security rules - Control access to your data