コレクション参照

コレクション参照を使うと、データベース内のドキュメントのコレクション（NoSQL）またはテーブル（SQL）にアクセスできます。

コレクション参照を使う理由

データの読み取り・書き込み・クエリ実行には出発点が必要です。コレクション参照は、クライアントコードを特定のコレクションまたはテーブルに接続し、単一のエントリポイントを通じてすべてのデータベース操作へ型安全にアクセスできるようにします。

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

コレクションの基本

コレクション参照は、データベース内の特定のコレクションまたはテーブルを指す「型付きポインタ」です。Squid Client SDK におけるすべてのデータ操作の出発点として機能します。

コレクション参照を作成するには、squid オブジェクトに対して collection メソッドを呼び出し、コレクション名と、型安全のためのオプションのジェネリック型パラメータを渡します。

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

外部データベースのテーブルにアクセスするには、第2引数に connector ID を渡します。connector ID は、Squid Console の connectors section で確認できます。

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

ジェネリック型指定

コレクション参照は、コレクション内のドキュメント形状を表すジェネリック型パラメータ T を受け取れます。これにより、すべての操作でコンパイル時の型安全が提供されます。

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

参照 ID

各コレクション参照インスタンスには、それを識別する一意の refId プロパティがあります。

Client code
usersCollection.refId; // Unique identifier string

クイックスタート

Step 1: データ型を定義する

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

Step 2: コレクション参照を作成する

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

Step 3: データをクエリして利用する

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	Method	Details
ドキュメント参照を取得する	`collection.doc(id)`	ドキュメント参照、ドキュメント ID
ドキュメントをクエリする	`collection.query()`	クエリ
コレクション間で Join する	`collection.joinQuery()`	コレクションおよびコネクタをまたいだデータの結合
OR でクエリを組み合わせる	`collection.or(query1, query2)`	OR クエリ
複数ドキュメントを挿入する	`collection.insertMany()`	データの追加
複数ドキュメントを削除する	`collection.deleteMany()`	データの削除
特定フィールドを投影する	`query.projectFields()`	フィールド投影

エラーハンドリング

Error	Cause	Solution
Collection not found	コレクション名が、既存のコレクションまたはテーブルのいずれとも一致しない	Squid Console でコレクション名を確認してください
Invalid connector ID	第2引数として渡した connector ID が存在しない	Squid Console の connectors section で connector ID を確認してください
Type mismatch at runtime	ジェネリック型パラメータが実際のドキュメント形状と一致しない	TypeScript の interface がコレクションスキーマと一致していることを確認してください

ベストプラクティス

常にジェネリック型パラメータを使用して、すべての操作でコンパイル時の型安全を得てください。

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

操作ごとに新しい参照を作るのではなく、コンポーネントやモジュール内でコレクション参照を再利用してください。
typo を防ぎ、connector の変更を簡単にするために、connector ID は定数に保存してください。
Client code
```
const POSTGRES_CONNECTOR = 'my_postgres_connector';
const orders = squid.collection<Order>('orders', POSTGRES_CONNECTOR);
```

コレクション参照を使うと、データベース内のドキュメントのコレクション（NoSQL）またはテーブル（SQL）にアクセスできます。​