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

ミューテーション

ミューテーションとは、ドキュメントのデータを変更するアクションのことです。これにより、オプティミスティック・アップデートを用いて、高速でレスポンシブなユーザー体験が実現されます。​

もし transaction 内で実行されない場合、全てのミューテーションはサーバー上で適用された後に解決される Promise を返します。

ミューテーションの適用​

ミューテーションは、クライアント上でオプティミスティックにローカル適用され、即座に反映されます。その後、変更は一貫性のあるクリーンなデータ状態を保証するために、非同期でサーバーに送信されます。

ミューテーションには、insert、delete、および update の3種類があります。各操作は、document reference 上で実行されます。

Insert​

Insert は、新しいドキュメントを作成するために使用されます。コレクションに新しいドキュメントを挿入するには、DocumentReference 上で insert メソッドを呼び出し、新しいドキュメントデータを引数として渡します:

Client code
try {
  await squid.collection<User>('users').doc('new_user_id').insert({
    name: 'John Doe',
    email: 'johndoe@example.com',
  });
  console.log('User added successfully');
} catch (error) {
  console.error(`Failed to add user ${error}`);
}
ヒント

バックエンドのセキュリティルールでは、各ミューテーションを誰が実行できるかを細かく制御することができます。これらのルールは、変更前後のドキュメントのスナップショットを含む、ミューテーションに関するすべての必要な詳細情報を含む MutationContext をパラメーターとして受け取ります。セキュリティルールの記述方法については、security rules をご参照ください。

Insert many​

insertMany メソッドは、複数のドキュメントを一度に効率的に挿入および/または更新するために使用されます。以下の例では、新しいユーザードキュメントの配列を追加しています:

Client code
const newDocuments = [
  {
    id: 'new_user_id1',
    data: {
      name: 'John Doe',
      email: 'johndoe@example.com',
    },
  },
  {
    id: 'new_user_id2',
    data: {
      name: 'Jan Smith',
      email: 'jansmith@example.com',
    },
  },
];

try {
  await squid.collection<User>('users').insertMany(newDocuments);
  console.log('Users added successfully');
} catch (error) {
  console.error(`Failed to add users ${error}`);
}

Update​

ドキュメントを更新するには、DocumentReference 上で update メソッドを呼び出し、部分的な更新データを含むオブジェクトを引数として渡します:

Client code
try {
  await squid.collection<User>('users').doc('existing_user_id').update({ email: 'new_email@example.com' });
  console.log('User updated successfully');
} catch (error) {
  console.error(`Failed to update user ${error}`);
}

また、DocumentReference 上で setInPath メソッドを呼び出し、プロパティへの path と新しい値を引数として渡すことで、ドキュメントの特定のプロパティを更新することもできます:

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

try {
  await userRef.setInPath('address.street', 'Main');
  console.log('Updated successfully');
} catch (error) {
  console.error(`Failed to update user ${error}`);
}

ドキュメントの特定のプロパティを削除するには、DocumentReference 上で deleteInPath メソッドを呼び出し、削除したいプロパティへの path を引数として渡します:

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

try {
  await userRef.deleteInPath('email');
  console.log('User email deleted successfully');
} catch (error) {
  console.error(`Failed to delete user email ${error}`);
}

Delete​

ドキュメントを削除するには、DocumentReference 上で delete メソッドを呼び出します:

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

try {
  await userRef.delete();
  console.log('User deleted successfully');
} catch (error) {
  console.error(`Failed to delete user ${error}`);
}

Delete many​

複数のドキュメントを一括で削除するには、deleteMany メソッドを使用します。deleteMany は、ドキュメントまたはドキュメントIDの配列をパラメーターとして受け取ります。

Client code
const staleDocs = await squid.collection<User>('users').query().eq('pending-delete', true);

try {
  await squid.collection<User>('users').deleteMany(staleDocs);
  console.log('users successfully deleted');
} catch (error) {
  console.error(`Failed to delete users ${error}`);
}