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

Document ID

Document ID は document の一意の identifier であり、server によって自動生成することも、user が手動で指定することもできます。​

Document ID を使用する理由​

database 内のすべての document には一意の identifier が必要です。Squid は、database type と schema に応じて、単純な string から複数 field にまたがる composite key まで、複数の ID format をサポートします。ID の仕組みを理解することで、document を正しく参照、作成、lookup できます。

概要​

Squid の built-in database は 2 種類の document ID をサポートします。一方、database connector では document ID に object が必要です。

Built-in database​

Squid の built-in database では、document ID は次の 2 種類のいずれかにできます。

  1. collection 内で一意の string。string は、多数の document の中から 1 つの document を識別する効果的な方法です。多くの場合、開発者は string ID にランダム生成された UUID を設定します。独自の一意な 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 形式の composite primary key。user が console で collection の schema を変更し、primary key を composite にした場合、ID は {employeeName: string, deptId: string} のような object 形式にする必要があります。これにより、複数 field を document ID として指定できます。たとえば、department 12345 の Jane Doe が誕生日を迎えた場合、次のように age を更新できます。
Client code
const collectionRef = squid.collection('employees');
const docRef = collectionRef.doc({ employeeName: 'Jane Doe', deptId: '12345' });
await docRef.update({ age: 31 });

Auto ID generation​

user が ID を指定せず、schema が ID を composite primary key にすることを要求していない場合、Squid により ID が自動生成されます。以下の例では、ID が自動的に生成されます。

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

External database connector​

built-in connector 以外の connector では、primary key が composite でない場合でも、document ID は object 形式である必要があります。

以下は、database connector 内に custom ID を持つ document を作成する例です。

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

Document ID による Query​

Document ID は、基盤となる primary key column 名を知らなくても、すべての connector で利用できる __docId__ pseudo-field を通じて query できます。docId() および docIds() query shortcut は、一般的な case をカバーします。

Client code
await squid.collection<User>('users').query().docId('user_abc123').snapshot();

composite primary key では、すべての key field を持つ object を渡します。

Client code
await squid
  .collection('inventory', 'CONNECTOR_ID')
  .query()
  .docId({ orgId: 'o1', itemId: 'i1' })
  .snapshot();

composite-key の __docId__ filter は equality operator（==、!=、in、not in）のみをサポートし、Elasticsearch および DynamoDB connector では利用できません。single-key filter は、すべての connector で完全な operator set をサポートします。詳細はdocument ID による filtering、ID filter による document の削除についてはquery による削除を参照してください。

Error Handling​

Error原因解決策
Invalid ID formatobject が必要な external connector に string ID を渡したexternal connector には object ID を使用します: doc({ id: 'value' })
Missing composite key fieldscomposite primary key に必要なすべての field を指定していないcomposite key schema で定義されているすべての field を含めます
ID conflict on insertすでに存在する ID を持つ document を insert した一意の ID を使用するか、既存 document を変更する場合は代わりに update() を呼び出します

Best Practices​

  1. built-in database で、単一 field が document を一意に識別する場合は、単純な lookup に string ID を使用します。

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

  2. department と employee name の組み合わせのように、複数 field が一意性を定義する場合は、composite key を使用します。

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

  3. primary key が single column の場合でも、external connector には常に object ID を使用します。これは connector type 間で一貫性を保つための Squid requirement です。

  4. log entry や event を作成する場合など、ID value を制御する必要がない場合は、自動生成 ID を使用します。

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