Collection reference

collection reference により、database 内の document collection（NoSQL）または table（SQL）に access できます。

Collection Reference を使用する理由

data の読み取り、書き込み、query を開始するための起点が必要です。collection reference は client code を特定の collection または table に接続し、単一の entry point を通じてすべての database operation への type-safe な access を提供します。

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 の基本

collection reference は、database 内の特定の collection または table を指す typed pointer です。Squid Client SDK におけるすべての data operation の開始点として機能します。

collection reference を作成するには、squid object の collection method を collection 名と、type safety 用の optional な generic type parameter を指定して呼び出します。

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

external database 内の table に access するには、2 番目の parameter として connector ID を渡します。connector ID は Squid Console の connectors section で確認できます。

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

Generic typing

collection reference は、collection 内の document の shape を表す generic type parameter T を受け入れます。これにより、すべての operation で compile-time type safety が提供されます。

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

各 collection reference instance には、それを識別する unique な refId property があります。

Client code
usersCollection.refId; // Unique identifier string

クイックスタート

ステップ 1: Data type を定義する

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

ステップ 2: Collection reference を作成する

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

ステップ 3: Data を query して使用する

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);
}

利用可能な operation

collection reference を取得すると、document への access、query の構築、bulk operation の実行に使用できます。

Operation	Method	詳細
Document reference を取得	`collection.doc(id)`	Document references、Document IDs
Document を query	`collection.query()`	Queries
Collection 間を join	`collection.joinQuery()`	Joining data across collections
OR で query を結合	`collection.or(query1, query2)`	OR queries
複数の document を insert	`collection.insertMany()`	Adding data
複数の document を delete	`collection.deleteMany()`	Deleting data
特定 field を project	`query.projectFields()`	Field projection

Error Handling

Error	原因	解決策
Collection not found	collection 名が既存の collection または table と一致しない	Squid Console で collection 名を確認する
Invalid connector ID	2 番目の parameter として渡した connector ID が存在しない	Squid Console の connectors section で connector ID を確認する
Type mismatch at runtime	generic type parameter が実際の document shape と一致しない	TypeScript interface が collection schema と一致することを確認する

ベストプラクティス

すべての operation に compile-time type safety を得るため、常に generic type parameter を使用します。

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');

operation ごとに新しい reference を作成するのではなく、component または module 全体でcollection reference を再利用します。

typo を回避し connector の変更を簡略化するため、connector ID を constant に保存します。

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

collection reference により、database 内の document collection（NoSQL）または table（SQL）に access できます。​