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

ドキュメントID

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

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

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

概要​

Squid のビルトインデータベースは 2 種類のドキュメントIDをサポートします。一方、database connectors ではドキュメントIDとして object が必要です。

ビルトインデータベース​

Squid のビルトインデータベースでは、ドキュメントIDは次の 2 種類のいずれかです。

  1. コレクション内で一意な文字列。文字列は、多数のドキュメントの中から 1 つのドキュメントを識別する効果的な方法です。多くの場合、開発者は文字列IDをランダムに生成された UUIDs に設定します。独自の一意な文字列を指定することもできます。
Client code
const collectionRef = squid.collection('users');
const docRef = collectionRef.doc('my_custom_id');
await docRef.insert({ name: 'John Doe', age: 30 });
  1. object 形式の複合主キー。ユーザーがコンソールでコレクションのスキーマを変更して主キーを複合にした場合、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 を複合主キーとして要求しない場合、ID は Squid によって自動生成されます。次の例では、ID は自動的に生成されます。

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

外部 database connectors​

ビルトイン以外の connector では、主キーが複合でない場合でも、ドキュメント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
Invalid ID format外部 connector に文字列IDを渡している（object が必要）外部 connectors には object ID を使用する: doc({ id: 'value' })
Missing composite key fields複合主キーに必要なすべてのフィールドを指定していない複合キーのスキーマで定義されているすべてのフィールドを含める
ID conflict on insertすでに存在する ID でドキュメントを insert しようとしている一意の ID を使用する。既存ドキュメントを変更するなら代わりに update() を呼ぶ

ベストプラクティス​

  1. ビルトインデータベースでは、単一フィールドでドキュメントを一意に識別できる場合、シンプルな検索には文字列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. 主キーが単一カラムであっても、外部 connectors では常に object ID を使用する。これは connector 種別間で一貫性を保つための Squid の要件です。

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

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