データのリストを操作する

データベース参照を取得する

データベースでデータの読み書きを行うには、DatabaseReference のインスタンスが必要です。

DatabaseReference ref = FirebaseDatabase.instance.ref();

リストの読み取りと書き込み

リストへのデータの追加

マルチユーザーアプリケーションでリストにデータを追加するには push() メソッドを使用します。指定した Firebase 参照に新しい子が追加されるたびに、push() メソッドは一意のキーを生成します。この自動生成されたキーをリスト内の新しい各要素に使用することで、書き込みの競合を伴わずに複数のクライアントが同時に子を同じ場所に追加できます。push() によって生成される一意のキーはタイムスタンプに基づいているため、リストのアイテムは自動的に時系列で並べ替えられます。

push() メソッドによって返された新しいデータを参照することで、子の自動生成されたキーの値を取得することも、子のデータを設定することもできます。push() 参照の .key プロパティには自動生成されたキーが含まれています。

この自動生成されたキーを使用すると、データ構造を平坦化しやすくなります。詳細については、データのファンアウトの例をご覧ください。

たとえば、次のように push() を使用すると、ソーシャルアプリケーションの投稿リストに新しい投稿を追加できます。

DatabaseReference postListRef = FirebaseDatabase.instance.ref("posts");
DatabaseReference newPostRef = postListRef.push();
newPostRef.set({
  // ...
});

child イベントのリッスン

push() メソッドによる新しい子の追加や、update() メソッドによる子の更新など、ノードの子に対して発生した特定のオペレーションに応じて child イベントがトリガーされます。

イベント	一般的な使用方法
`onChildAdded`	アイテムのリストを取得します。また、アイテムのリストへの追加をリッスンします。このイベントは既存の子ごとに 1 回トリガーされます。さらに、指定されたパスに新しい子が追加されると、そのたびに再びトリガーされます。リスナーには、新しい子のデータを含んでいるスナップショットが渡されます。
`onChildChanged`	リスト内のアイテムに対する変更がないかリッスンします。子ノードが修正されるたびにこのイベントがトリガーされます。この変更には、子ノードの子孫に対する変更も含まれます。イベントリスナーに渡されるスナップショットには、子の更新済みデータが含まれています。
`onChildRemoved`	リストから削除されたアイテムがないかリッスンします。このイベントは直接の子が削除されるとトリガーされます。コールバックブロックに渡されるスナップショットには、削除された子のデータが含まれています。
`onChildMoved`	並べ替えリストの項目順変更をリッスンします。onChildMoved イベントは常に、（現在の order-by メソッドに基づく）並べ替え変更が原因の onChildChanged イベントに後続します。

それぞれのイベントを組み合わせると、データベース内の特定のノードの変更内容をリッスンするうえで役立つことがあります。たとえば、ソーシャルブログアプリでは、以下に示すように、これらのメソッドを組み合わせて使用して投稿のコメントでのアクティビティをモニタリングできます。

final commentsRef = FirebaseDatabase.instance.ref("post-comments/$postId");
commentsRef.onChildAdded.listen((event) {
  // A new comment has been added, so add it to the displayed list.
});
commentsRef.onChildChanged.listen((event) {
  // A comment has changed; use the key to determine if we are displaying this
  // comment and if so displayed the changed comment.
});
commentsRef.onChildRemoved.listen((event) {
  // A comment has been removed; use the key to determine if we are displaying
  // this comment and if so remove it.
});

value イベントのリッスン

データのリストを読み取るための推奨される方法は child イベントのリッスンですが、リスト参照で value イベントをリッスンするのが有効な場合もあります。

データのリストに value リスナーをアタッチすると、データのリスト全体が単一のスナップショットとして返されるため、ループして個別の子にアクセスできます。

クエリで一致が 1 つしかない場合でも、スナップショットはリストになります（ただし、アイテムは 1 つしか含まれていません）。アイテムにアクセスするには、結果をループする必要があります。

myTopPostsQuery.onValue.listen((event) {
  for (final child in event.snapshot.children) {
    // Handle the post.
  }
}, onError: (error) {
  // Error.
});

このパターンは、child が追加された他のイベントをリッスンするのではなく、単一のオペレーションでリストのすべての子を取得する場合に便利です。

データの並べ替えとフィルタリング

Query クラスを使用すると、キー、値、または子の値で並べ替えられたデータを取得できます。また、並べ替えられた結果を、特定の件数またはある範囲のキーや値に限定するようフィルタリングできます。

データを並べ替える

並べ替えられたデータを取得するには、最初にいずれかの order-by メソッドを指定して、結果の並べ替え方法を決定します。

メソッド	用途
`orderByChild()`	指定した子キーまたはネストされた子のパスの値によって結果を並べ替えます。
`orderByKey()`	子キーによって結果を並べ替えます。
`orderByValue()`	子の値によって結果を並べ替えます。

同時に使用できる order-by メソッドは 1 つだけです。同じクエリで order-by メソッドを複数回呼び出すとエラーがスローされます。

次の例では、スターの数で並べ替えられたユーザーの上位の投稿のリストを取得する方法について示しています。

final myUserId = FirebaseAuth.instance.currentUser?.uid;
final topUserPostsRef = FirebaseDatabase.instance
    .ref("user-posts/$myUserId")
    .orderByChild("starCount");

ここでは、子リスナーと組み合わせて、ユーザー ID に基づいてデータベース内のパスからクライアントをユーザーの投稿と同期させるクエリを定義しています。ユーザー ID は、それぞれの投稿が受けたスターの数で並べ替えられています。このように ID をインデックスキーとして使用する手法はデータのファンアウトと呼ばれています。詳細については、データベースの構造化をご覧ください。

orderByChild() メソッドの呼び出しでは、結果を並べ替えるための子キーを指定します。この場合、投稿はそれぞれの子 "starCount" の値によって並べ替えられます。次のようなデータの場合、クエリはネストされた子によって並べ替えることもできます。

"posts": {
  "ts-functions": {
    "metrics": {
      "views" : 1200000,
      "likes" : 251000,
      "shares": 1200,
    },
    "title" : "Why you should use TypeScript for writing Cloud Functions",
    "author": "Doug",
  },
  "android-arch-3": {
    "metrics": {
      "views" : 900000,
      "likes" : 117000,
      "shares": 144,
    },
    "title" : "Using Android Architecture Components with Firebase Realtime Database (Part 3)",
    "author": "Doug",
  }
},

この場合、orderByChild() 呼び出しで、ネストされた子への相対パスを指定することにより、metrics キーの下にネストされた値によってリスト要素を並べ替えることができます。

final mostViewedPosts =
    FirebaseDatabase.instance.ref('posts').orderByChild('metrics/views');

他の種類のデータを並べ替える方法について詳しくは、クエリデータが並べ替えられる仕組みをご覧ください。

データのフィルタリング

データをフィルタリングするには、クエリの構築時に、制限メソッドまたは範囲メソッドのいずれかを order-by メソッドと組み合わせることができます。

メソッド	用途
`limitToFirst()`	並べ替えられた結果リストの先頭から返すアイテムの最大数を設定します。
`limitToLast()`	並べ替えられた結果リストの末尾から返すアイテムの最大数を設定します。
`startAt()`	選択した order-by メソッドに応じて、指定したキーまたは値以上のアイテムを返します。
`startAfter()`	選択した order-by メソッドに応じて、指定したキーまたは値より大きいアイテムを返します。
`endAt()`	選択した order-by メソッドに応じて、指定したキーまたは値以下のアイテムを返します。
`endBefore()`	選択した order-by メソッドに応じて、指定したキーまたは値より小さいアイテムを返します。
`equalTo()`	選択した order-by メソッドに応じて、指定したキーまたは値に等しいアイテムを返します。

order-by メソッドとは異なり、複数の制限関数または範囲関数を組み合わせることができます。たとえば、startAt() メソッドと endAt() メソッドを組み合わせて、結果を特定の範囲の値に制限できます。

結果の個数を制限する

limitToFirst() メソッドと limitToLast() メソッドを使用して、特定のイベントに対して同期する子の最大数を設定できます。たとえば、limitToFirst() を使用して上限 100 を設定した場合は、初期状態で最大 100 個の onChildAdded イベントのみを受け取ります。Firebase データベースに保存されているアイテムが 100 個よりも少ない場合、それぞれのアイテムに対する onChildAdded イベントが発生します。

アイテムの変更に応じて、クエリに加わったアイテムに対する onChildAdded イベントと、クエリから外れたアイテムに対する onChildRemoved イベントを受け取り、合計数が 100 に保たれます。

次の例は、サンプルのブログアプリで全ユーザーの最新 100 件の投稿のリストを取得するクエリを定義する方法を示しています。

final recentPostsRef = FirebaseDatabase.instance.ref('posts').limitToLast(100);

この例では、クエリを定義しているだけです。データを実際に同期するには、アタッチされたリスナーが必要です。

キーまたは値によるフィルタリング

startAt()、startAfter()、endAt()、endBefore()、equalTo() を使用して、クエリ用に任意の始点、終点、同値点を選択できます。これは、データをページ分けするときや、特定の値を持つ子があるアイテムを検索するときに役立ちます。

クエリデータが並べ替えられる仕組み

このセクションでは、Query クラスのそれぞれの order-by メソッドでデータがどのように並べ替えられるのかを説明します。

`orderByChild`

orderByChild() を使用すると、指定した子キーを含むデータは次のように並べ替えられます。

指定した子キーに null 値を持つ子が最初に来ます。
指定した子キーの値が false である子が次に来ます。複数の子が値 false を持つ場合、キーで辞書順に並べ替えられます。
指定した子キーの値が true である子が次に来ます。複数の子が値 true を持つ場合、キーで辞書順に並べ替えられます。
数値を持つ子が次に来ます。ただし、昇順に並べ替えられます。指定した子ノードに同じ数値を持つ複数の子がある場合、キーで並べ替えられます。
文字列は数値の後に来て、辞書順で昇順に並べ替えられます。指定した子ノードに同じ値を持つ複数の子がある場合、キーで辞書順に並べ替えられます。
オブジェクトが最後に来て、キー名の辞書順で昇順に並べ替えられます。

`orderByKey`

orderByKey() を使用してデータを並べ替えると、キー名で昇順にデータが返されます。

32 ビット整数として解析できるキーを持つ子が最初に来ます。ただし、昇順に並べ替えられます。
文字列値をキーとして持つ子が次に来ます。ただし、辞書順で昇順に並べ替えられます。

`orderByValue`

orderByValue() を使用すると、子がその値で並べ替えられます。並べ替えの条件は、指定した子キーの値の代わりにノードの値が使用されるという点を除いて、orderByChild() の場合と同じです。

リスナーのデタッチ

コールバックを削除するには、Firebase データベース参照で off() メソッドを呼び出します。

単一のリスナーは、パラメータとしてリスナーを off() に渡すと削除できます。off() を引数なしで呼び出すと、その場所にあるすべてのリスナーが削除されます。

親リスナーで off() を呼び出しても、その子ノードに登録されているリスナーが自動的に削除されるわけではありません。また、コールバックを削除するために子リスナーで off() も呼び出す必要があります。