Anuncio de Cloud Firestore (Beta): Prueba la nueva base de datos escalable y flexible de Firebase y Google Cloud Platform. Obtén más información sobre Cloud Firestore.

Trabaja con listas de datos en la Web

Obtén una referencia a una base de datos

Para leer la base de datos o escribir en ella, necesitas la siguiente instancia de firebase.database.Reference:

// Get a reference to the database service
var database = firebase.database();

Lectura y escritura de listas

Agrega datos a una lista de datos

Usa el método push() para agregar datos a una lista en aplicaciones multiusuario. El método push() genera una clave única cada vez que se agrega un nuevo elemento secundario a la referencia de Firebase especificada. Cuando se usan estas claves generadas automáticamente para cada elemento nuevo de la lista, varios clientes pueden agregar elementos secundarios a la misma ubicación al mismo tiempo sin conflictos de escritura. La clave única generada por push() se basa en una marca de tiempo. Por lo tanto, los elementos de las listas se ordenan cronológicamente de forma automática.

Puedes usar la referencia a los nuevos datos que brinda el método push() para obtener el valor de la clave autogenerada del elemento secundario o definir los datos del elemento secundario. La propiedad .key de una referencia push() contiene la clave autogenerada.

Puedes usar estas claves generadas de manera automática para simplificar la compactación de tu estructura de datos. Para obtener más información, consulta el ejemplo de distribución de datos.

Por ejemplo, push() podría usarse para agregar un nuevo elemento a una lista de publicaciones en una aplicación social:

// Create a new post reference with an auto-generated id
var newPostRef = postListRef.push();
newPostRef.set({
    // ...
});

Detecta eventos secundarios

Los eventos de nivel secundario se activan en respuesta a operaciones específicas que afectan a un elemento de nivel secundario de un nodo durante una operación, como cuando se agrega un nuevo elemento secundario mediante el método push() o cuando se lo actualiza con el método update().

Evento Uso normal
child_added Recupera listas de elementos o detecta elementos agregados a una lista. Este evento se activa una vez por cada elemento secundario existente y otra vez cuando se agrega un elemento secundario nuevo a la ruta de acceso especificada. El agente de escucha recibe una instantánea que contiene los datos del nuevo elemento secundario.
child_changed Detecta cambios en los elementos de una lista. Este evento se activa cuando se modifica un nodo secundario. Esto incluye cualquier modificación en los descendientes del nodo secundario. La instantánea que se pasa al agente de escucha de eventos contiene los datos actualizados del elemento secundario.
child_removed Detecta cuando se quitan elementos de una lista. Este evento se activa cuando se quita un elemento secundario inmediato.La instantánea que se pasa al bloque de devoluciones de llamada contiene los datos del elemento secundario que se quitó.
child_moved Detecta cambios en el orden de los elementos de una lista ordenada. Los eventos child_moved siempre siguen al evento child_changed que generó el cambio en el orden de los elementos (en función del método de ordenamiento actual).

Cada uno de estos, en combinación, puede ser útil para detectar cambios en un nodo específico de una base de datos. Por ejemplo, una app social de blogs podría usar estos métodos en combinación para supervisar la actividad en los comentarios de una publicación, como se muestra a continuación:

var commentsRef = firebase.database().ref('post-comments/' + postId);
commentsRef.on('child_added', function(data) {
  addCommentElement(postElement, data.key, data.val().text, data.val().author);
});

commentsRef.on('child_changed', function(data) {
  setCommentValues(postElement, data.key, data.val().text, data.val().author);
});

commentsRef.on('child_removed', function(data) {
  deleteComment(postElement, data.key);
});

Detecta eventos de valores

Si bien escuchar para detectar eventos secundarios es la manera recomendada de leer listas de datos, escuchar para detectar eventos de valores en una referencia de lista puede ser útil en algunas situaciones.

Si agregas un observador de value a una lista de datos, el resultado será una lista completa de los datos en forma de una sola instantánea. Si le aplicas un bucle a ese resultado, puedes acceder a cada elemento secundario.

Incluso cuando hay una sola coincidencia para la consulta, la instantánea es una lista, aunque contenga un solo elemento. Para acceder al elemento, debes aplicar un bucle al resultado:

ref.once('value', function(snapshot) {
  snapshot.forEach(function(childSnapshot) {
    var childKey = childSnapshot.key;
    var childData = childSnapshot.val();
    // ...
  });
});

Este patrón puede ser útil cuando quieres recuperar todos los elementos secundarios de una lista en una sola operación, en lugar de escuchar para detectar cada evento secundario que se agrega.

Cómo ordenar y filtrar datos

Puedes usar la clase Query de Realtime Database para recuperar los datos organizados por clave, por valor o por valor del elemento secundario. También puedes filtrar el resultado organizado a una cantidad específica de resultados o un rango de claves o valores.

Ordena los datos

Para recuperar datos ordenados, comienza por especificar uno de los métodos de ordenamiento, a fin de determinar cómo se presentarán los resultados:

Método Uso
orderByChild() Ordena los resultados según el valor de una clave secundaria especificada o una ruta de acceso secundaria anidada.
orderByKey() Ordena los resultados según las claves secundarias.
orderByValue() Ordena los resultados según los valores secundarios.

Puedes usar solo un método de ordenamiento a la vez. Si llamas un método de ordenamiento varias veces en la misma consulta, se genera un error.

El siguiente ejemplo demuestra cómo podrías recuperar una lista de las principales publicaciones de un usuario según la cantidad de estrellas que tienen:

var myUserId = firebase.auth().currentUser.uid;
var topUserPostsRef = firebase.database().ref('user-posts/' + myUserId).orderByChild('starCount');

Esto define una consulta que, cuando se combina con un agente de escucha de elementos secundarios, sincroniza el cliente con las publicaciones del usuario en la ruta de la base de datos, ordenadas según la cantidad de estrellas que recibió cada publicación. Esta técnica de usar ID como claves de índice se denomina "distribución de datos”. Puedes obtener más información al respecto en Estructura tu base de datos.

La llamada al método orderByChild() especifica la clave secundaria según la que se deben ordenar los resultados. En este caso, las publicaciones se ordenan según el valor del elemento secundario "starCount" respectivo. Las consultas también se pueden ordenar por campos secundarios anidados si tienes datos que lucen de la siguiente forma:

"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",
  }
},

En este caso, podemos ordenar los elementos de nuestra lista según los valores anidados en la clave metrics. Para ello, debemos especificar la ruta de acceso relativa al elemento secundario anidado presente en nuestra llamada a orderByChild().

 
var mostViewedPosts = firebase.database().ref('posts').orderByChild('metrics/views');

Para obtener más información sobre cómo se ordenan otros tipos de datos, consulta la sección Cómo se ordenan los datos de las consultas.

Cómo filtrar datos

Para filtrar datos, puedes combinar cualquiera de los métodos de límite o rango con un método de ordenamiento cuando generes una consulta.

Método Uso
limitToFirst() Configura la cantidad máxima de elementos que pueden mostrarse desde el comienzo de la lista de resultados ordenada.
limitToLast() Configura la cantidad máxima de elementos que pueden mostrarse desde el final de la lista de resultados ordenada.
startAt() Muestra elementos con un valor igual o superior a la clave o el valor que se especifica según el método de ordenamiento seleccionado.
endAt() Muestra elementos con un valor inferior o igual a la clave o el valor que se especifica según el método de ordenamiento seleccionado.
equalTo() Muestra elementos con un valor igual a la clave o el valor que se especifica según el método de ordenamiento seleccionado.

A diferencia de los métodos de ordenamiento, las funciones de límite y rango pueden combinarse. Por ejemplo, puedes combinar los métodos startAt() y endAt() para limitar los resultados a un rango de valores específico.

Limita el número de resultados

Puedes usar los métodos limitToFirst() y limitToLast() para definir la cantidad máxima de elementos secundarios que deben sincronizarse para un evento determinado. Por ejemplo, si usas limitToFirst() para establecer un límite de 100, inicialmente solo recibes 100 eventos de tipo child_added. Si hay menos de 100 elementos almacenados en la base de datos de Firebase, se activa un evento child_added por cada elemento.

A medida que cambien los elementos, recibirás eventos child_added por los elementos que ingresen en la consulta y eventos child_removed por los elementos que la dejen, de modo que la cantidad total continúe siendo 100.

El siguiente ejemplo demuestra cómo una app de blog define una consulta para recuperar una lista de las 100 publicaciones más recientes de todos los usuarios:

var recentPostsRef = firebase.database().ref('posts').limitToLast(100);

En este ejemplo, solo se define una consulta. A fin de sincronizar los datos realmente, se necesitaría un agente de escucha agregado.

Filtra por clave o valor

Puedes usar startAt(), endAt() y equalTo() para seleccionar puntos arbitrarios de inicio, fin y equivalencia para las consultas. Esto puede ser útil para paginar datos o para encontrar elementos con elementos secundarios que tengan un valor específico.

Cómo se ordenan los datos de las consultas

En esta sección, se explica cómo se ordenan los datos en cada uno de los métodos de ordenamiento de la clase Query.

orderByChild

Cuando usas orderByChild(), los datos que contienen la clave secundaria especificada se ordenan de la siguiente manera:

  1. Los elementos secundarios cuyas claves secundarias especificadas posean el valor null irán en primer lugar.
  2. A continuación, aparecerán los elementos secundarios que tengan el valor false en la clave secundaria especificada. Si hay varios elementos secundarios con el valor false, se ordenarán lexicográficamente por clave.
  3. A continuación, aparecerán los elementos secundarios que tengan el valor true en la clave secundaria especificada. Si hay varios elementos secundarios con el valor true, se ordenan de manera lexicográfica según la clave.
  4. Luego vienen los elementos secundarios con valor numérico, que se ordenan en sentido ascendente. Si varios elementos secundarios tienen el mismo valor numérico en el nodo secundario especificado, se ordenan según la clave.
  5. Las strings van después de los números y se ordenan de manera lexicográfica, en sentido ascendente. Si varios elementos secundarios tienen el mismo valor en el nodo secundario especificado, se ordenan de manera lexicográfica según la clave.
  6. Los objetos quedan en último lugar y se ordenan de manera lexicográfica según su clave, en orden ascendente.

orderByKey

Cuando ordenas los datos con orderByKey(), los datos se presentan en orden ascendente, según la clave.

  1. Los elementos secundarios con una clave que puede analizarse como un elemento entero de 32 bits van primero, ordenados en sentido ascendente.
  2. Los campos secundarios con un valor de string como clave van después y se ordenan de manera lexicográfica, en sentido ascendente.

orderByValue

Cuando usas orderByValue(), los elementos secundarios se ordenan según el valor. Los criterios de ordenamiento son los mismos que en orderByChild(), pero se usa el valor del nodo en lugar del valor de una clave secundaria especificada.

Desvincula agentes de escucha

Para quitar las devoluciones de llamada, llama al método off() en tu referencia de la base de datos de Firebase.

Para quitar un solo agente de escucha, puedes pasarlo como parámetro a off(). Si llamas a off() en la ubicación sin argumentos, se quitarán todos los agentes de escucha de esa ubicación.

Si llamas a off() en un agente de escucha primario, no se quitan automáticamente los agentes de escucha registrados en sus nodos secundarios. Deberás llamar a off() también en todos los agentes de escucha secundarios para quitar la devolución de llamada.

Próximos pasos

Enviar comentarios sobre...

Firebase Realtime Database
Si necesitas ayuda, visita nuestra página de asistencia.