Skip to main content

Document IDs

Document IDs are an essential part of Squid's data model, and they play a crucial role in identifying and accessing specific documents in a collection. In Squid, document IDs are unique identifiers that can be either automatically generated by the server or manually specified by the user. There are different requirements for document IDs based on whether you use Squid's built-in database or other external database integrations. If you use Squid with a non-built-in database, follow the directions in the Non-built-in integrations section.

Built-in database

In the built-in database integration, document IDs can be one of two types:

  1. A string that is unique within the collection. A string is an effective way to identify one document from many others. Often, developers will set string IDs to be randomly generated UUIDs. You can also provide your own unique string:
Client code
const collectionRef = squid.collection('users');
const docRef = collectionRef.doc('my_custom_id');
await docRef.insert({ name: 'John Doe', age: 30 });
  1. Composite primary keys, which take the form of an object. If the user modifies the schema of a collection in the console and makes the primary key composite, the ID must be in the form of an object, such as {employeeName: string, deptId: string}. This allows the user to specify multiple fields as the document ID. For example, if Jane Doe in department 12345 just celebrated her birthday, we may update her age as follows:
Client code
const collectionRef = squid.collection('employees');
const docRef = collectionRef.doc({ employeeName: 'Jane Doe', deptId: '12345' });
await docRef.update({ age: 31 });

Auto ID generation

an ID is auto generated by Squid when the user does not specify an ID and the schema does not require the ID to be a composite primary key. When the user omits the ID in the doc() method, the ID will be automatically created by the server when the data is inserted. Then, a local placeholder ID is replaced by the server-generated one, ensuring that the IDs are synced and correct. In the example below, the ID is automatically generated:

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

Non-built-in integrations

For any non-built-in integration, the document ID must be in the form of an object, even if the primary key is not composite. This ensures consistency across different integrations and simplifies the handling of document IDs in Squid.

Here's an example of how to create a document with a custom ID in a non-built-in integration:

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

By understanding how document IDs work in Squid, you can create and manage documents more effectively and efficiently.