メインコンテンツまでスキップ

コレクション参照

コレクション参照を使用すると、データベース内のドキュメントのコレクション（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');

ジェネリック型付け​

コレクション参照は、コレクション内のドキュメントの形（shape）を表すジェネリック型パラメータ 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

クイックスタート​

ステップ 1: データ型を定義する​

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

ステップ 2: コレクション参照を作成する​

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

ステップ 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);
}

利用可能な操作​

コレクション参照を取得したら、それを使ってドキュメントへアクセスし、クエリを構築し、バルク操作を実行できます。

操作メソッド詳細
ドキュメント参照を取得するcollection.doc(id)ドキュメント参照, Document IDs
ドキュメントをクエリするcollection.query()クエリ
コレクション間で join するcollection.joinQuery()コレクションとコネクタをまたいだデータの join
OR でクエリを組み合わせるcollection.or(query1, query2)OR クエリ
複数ドキュメントを insert するcollection.insertMany()データの追加
複数ドキュメントを削除するcollection.deleteMany()データの削除
特定フィールドを投影するquery.projectFields()フィールド投影

エラーハンドリング​

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

ベストプラクティス​

  1. 常にジェネリック型パラメータを使用することで、すべての操作でコンパイル時の型安全性を得られます。

    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. 操作ごとに新しく作成するのではなく、コンポーネントやモジュール内でコレクション参照を再利用してください。

  3. connector ID を定数に保存して、タイプミスを防ぎ、connector の変更を簡単にします。

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

関連項目​