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

ドキュメントID

ドキュメントIDはドキュメントの一意な識別子であり、サーバーによって自動生成することも、ユーザーが手動で指定することもできます。​

ドキュメントIDを使用する理由​

データベース内のすべてのドキュメントには一意の識別子が必要です。Squid は、データベースの種類とスキーマに応じて、単純な文字列から複数フィールドにまたがる複合キーまで、複数の ID 形式をサポートします。ID の仕組みを理解することで、ドキュメントを正しく参照・作成・検索できるようになります。

概要​

Squid の組み込みデータベースは 2 種類のドキュメントIDをサポートします。一方、データベースコネクタでは、ドキュメントIDは object である必要があります。

組み込みデータベース​

Squid の組み込みデータベースでは、ドキュメントIDは次の 2 種類のいずれかになります。

  1. コレクション内で一意な string。string は、多数のドキュメントの中から 1 つのドキュメントを識別する効果的な方法です。多くの場合、開発者は string ID をランダム生成された UUIDs に設定します。独自の一意な string を指定することもできます。
Client code
const collectionRef = squid.collection('users');
const docRef = collectionRef.doc('my_custom_id');
await docRef.insert({ name: 'John Doe', age: 30 });
  1. object 形式の複合 primary key。ユーザーがコンソールでコレクションのスキーマを変更し、primary key を複合にした場合、ID は {employeeName: string, deptId: string} のような object 形式でなければなりません。これにより、複数のフィールドをドキュメントIDとして指定できます。たとえば、部門 12345 の Jane Doe が誕生日を迎えた場合、次のように年齢を更新できます。
Client code
const collectionRef = squid.collection('employees');
const docRef = collectionRef.doc({ employeeName: 'Jane Doe', deptId: '12345' });
await docRef.update({ age: 31 });

ID の自動生成​

ユーザーが ID を指定せず、かつスキーマが ID を複合 primary key として要求しない場合、ID は Squid により自動生成されます。以下の例では、ID は自動的に生成されます。

Client code
const collectionRef = squid.collection('users');
await collectionRef.doc().insert({ name: 'John Doe', age: 30 });

外部データベースコネクタ​

組み込み以外のコネクタでは、primary key が複合でない場合でも、ドキュメントIDは object 形式でなければなりません。

以下は、database connector でカスタム ID を指定してドキュメントを作成する例です。

Client code
const collectionRef = squid.collection('users', 'CONNECTOR_ID');
const docRef = collectionRef.doc({ id: 'my_custom_id' });
await docRef.insert({ name: 'John Doe', age: 30 });

エラーハンドリング​

ErrorCauseSolution
無効な ID 形式object が必要な external connector に string ID を渡しているexternal connectors では object ID を使用: doc({ id: 'value' })
複合キーのフィールド不足複合 primary key に必要なすべてのフィールドを提供していない複合キーのスキーマで定義されたすべてのフィールドを含める
insert 時の ID 競合すでに存在する ID でドキュメントを insert している一意の ID を使用する。既存ドキュメントを変更する場合は代わりに update() を呼ぶ

ベストプラクティス​

  1. 組み込みデータベースで、単一フィールドでドキュメントを一意に識別できる場合は、単純な lookup には string ID を使用します。

    Client code
    const userRef = squid.collection<User>('users').doc('user_abc123');

  2. 部門と従業員名の組み合わせなど、複数フィールドで一意性が定義される場合は、複合キーを使用します。

    Client code
    const empRef = squid.collection('employees').doc({
      deptId: 'engineering',
      employeeId: 'emp_456',
    });

  3. 外部コネクタでは常に object ID を使用します。primary key が単一カラムであっても同様です。これはコネクタ種別間での一貫性のための Squid の要件です。

  4. ログエントリやイベントの作成など、ID 値を制御する必要がない場合は、自動生成 ID を使用します。

    Client code
    await squid.collection('events').doc().insert({ type: 'click', timestamp: Date.now() });