Overview
Un filtro modifica una consulta entrante de MongoDB para devolver solo un subconjunto de los resultados que coincidan con la consulta. Añadir un filtro a una colección permite controlar la forma de los documentos consultados y mejorar el rendimiento de las consultas.
Los filtros añaden parámetros de consulta adicionales y omiten campos de los resultados de la consulta antes de que Atlas App Services la ejecute. Cada filtro tiene tres componentes:
Unaexpresión "aplicar cuando" que determina si el filtro se aplica a una solicitud entrante. Puede usar variables como
%%usery%%requesten la expresión "aplicar cuando". Sin embargo, no se pueden usar expansiones que hagan referencia a un documento como%%root, ya que App Services evalúa la expresión "aplicar cuando" antes de leer cualquier documento.Una expresión de consulta opcional, que se fusiona con la consulta existente de cualquier solicitud a la que se aplica el filtro.
Un documento de proyección opcional, que utiliza la sintaxis de proyección estándar de MongoDB y se fusiona con la proyección existente de cualquier solicitud a la que se aplique el filtro.
Cómo aplica filtros App Services
App Services evalúa y aplica filtros a todas las solicitudes de MongoDB donde se aplican reglas, excepto las solicitudes de sincronización de dispositivos. Algunos ejemplos de solicitudes de MongoDB filtrables son:
Una consulta sobre una colección.
Una escritura en un documento.
Un filtro se aplica a una solicitud dada si suexpresión "aplicar cuando" se evalúa como verdadera en el contexto de dicha solicitud. Si un filtro se aplica a una solicitud, App Services fusiona la consulta o proyección del filtro con la consulta y proyección existentes de la operación solicitada.
Se pueden aplicar varios filtros a una sola solicitud.
App Services aplica filtros a la solicitud antes de enviarla a MongoDB.
Ejemplo
Una colección contiene varios millones de documentos y tiene un rol con la siguiente expresión "aplicar cuando":
{ "owner_id": "%%user.id" }
Si no se aplica ningún filtro, App Services evaluará un rol para cada documento que coincida con la consulta. Sabemos que Servicios de aplicación retendrá cualquier documento que no tenga el id del usuario como valor del campo owner_id, así que ahorramos tiempo y recursos de computación aplicando un predicado adicional de query que excluye esos documentos antes de que Servicios de aplicación evalúe cualquier rol:
Aplicar cuando | Query | Proyección |
|---|---|---|
|
|
|
Definir filtros
Puede usar filtros para optimizar las consultas, minimizar la sobrecarga de procesamiento y proteger los datos confidenciales. Los filtros son especialmente útiles para problemas transversales que afectan a algunas o todas sus consultas.
Considere usar filtros si desea un sistema centralizado para:
Restringir las consultas a un subconjunto de todos los documentos
Omitir datos confidenciales o campos no utilizados
Ejemplo
En una aplicación de votación donde algunos usuarios aceptaron compartir su voto de forma anónima, puede usar el siguiente filtro para restringir todas las consultas a un subconjunto anónimo de los datos existentes:
{ "name": "AnonymizeVotes", "apply_when": true, "query": { "shareVoteAnonymous": true }, "project": { "_id": 0, "age": 1, "vote": 1 } }
{ "_id": ObjectId(...), "name": "sarah", age: 42, "vote": "yes", "shareVoteAnonymous": true } { "_id": ObjectId(...), "name": "andy", age: 22, "vote": "no", "shareVoteAnonymous": true } { "_id": ObjectId(...), "name": "jennifer", age: 37, "vote": "yes", "shareVoteAnonymous": false } { "_id": ObjectId(...), "name": "rick", age: 43, "vote": "no", "shareVoteAnonymous": true } { "_id": ObjectId(...), "name": "tom", age: 64, "vote": "yes", "shareVoteAnonymous": false } { "_id": ObjectId(...), "name": "bob", age: 67, "vote": "yes", "shareVoteAnonymous": true }
{ age: 42, "vote": "yes" } { age: 22, "vote": "no" } { age: 37, "vote": "yes" } { age: 43, "vote": "no" } { age: 64, "vote": "yes" } { age: 67, "vote": "yes" }
Procedimiento
Puede definir filtros para colecciones específicas en su clúster vinculado desde la interfaz de usuario de App Services o implementando archivos de configuración con Realm CLI:
Nota
Esta guía requiere una fuente de datos MongoDB Atlas vinculada.
Especifique la expresión Aplicar cuando
En el Apply When cuadro de entrada, introduzca una expresión de regla que defina cuándo se aplica el filtro a una consulta. Si la expresión se evalúa como true para una consulta entrante, App Services agrega los Filter Query parámetros a la consulta entrante.
Importante
Atlas App Services evalúa y aplica filtros antes de leer cualquier documento, por lo que no se pueden usar expansiones de documentos de MongoDB en la expresión "Aplicar cuando" de un filtro. Sin embargo, sí se pueden usar otras expansiones %%user como, %%values y.%function
Especificar los predicados de consulta de filtro
En el cuadro de entrada Query, especifique un documento que contenga predicados de consulta adicionales para combinarlos en la consulta entrante al aplicar el filtro. Por ejemplo, un filtro que retiene documentos con un score inferior a 20 podría usar la siguiente consulta de filtro:
{ "score": { "$gt": 20 } }
Especificar la proyección del filtro
En el cuadro de entrada Projection, especifique un documento que contenga un documento de proyección para fusionar con la consulta entrante cuando se aplica el filtro.
Por ejemplo, un filtro que retiene los campos career_stats y personal de los documentos podría utilizar la siguiente proyección de filtro:
{ "career_stats": 0, "personal": 0 }
Obtenga la última versión de su aplicación
Para definir filtros para una colección con servicios de aplicaciones, necesita una copia local de los archivos de configuración de su aplicación.
Para extraer una copia local de la última versión de su aplicación, ejecute lo siguiente:
appservices pull --remote="<Your App ID>"
Tip
También puedes descargar una copia de los archivos de configuración de tu aplicación desde la pantalla Deploy > Export App en la Interfaz de usuario Realm.
Agregar un archivo de configuración de reglas
Para definir o modificar roles para una colección, abra el archivo de configuración rules.json dentro del directorio de configuración de la colección.
Tip
Andamiaje de la colección
Si aún no ha definido reglas o un esquema para la colección, debe crear manualmente su directorio de configuración y schema.json:
# Create the collection's configuration directory mkdir -p data_sources/<service>/<db>/<collection> # Create the collection's schema file echo '{}' >> data_sources/<service>/<db>/<collection>/rules.json
El archivo de configuración debe tener la siguiente forma general:
{ "database": "<Database Name>", "collection": "<Collection Name>", "roles": [], "filters": [] }
Nota
Esta guía se centra en la creación de filters para la colección. Consulte las demás guías de configuración para aprender a definir roles y permisos, y a aplicar esquemas.
Nota
Las fuentes de datos federadas no admiten reglas ni esquemas. Solo se puede acceder a ellas desde una función del sistema.
Agregar uno o más filtros
Agregue un documento a la matriz filters por cada filtro que desee configurar. Los documentos de filtro tienen el siguiente formato:
{ "name": "<Filter Name>", "apply_when": { Expression }, "query": { MongoDB Query }, "projection": { MongoDB Projection } }
Campo | Descripción | |
|---|---|---|
namestring | Obligatorio. El nombre del filtro. Los nombres de los filtros son útiles para identificarlos y distinguirlos. Limitado a 100 caracteres o menos. | |
apply_whenobject | Una expresión que determina cuándo se aplica este filtro a una operación MongoDB entrante. ImportanteAtlas App Services evalúa y aplica filtros antes de leer cualquier documento, por lo que no se pueden usar expansiones de documentos de MongoDB en la expresión "Aplicar cuando" de un filtro. Sin embargo, sí se pueden usar otras expansiones | |
queryobjectDefault: {} | Una consulta de MongoDB que App Services fusiona en la consulta existente de una operación filtrada. EjemploUn filtro retiene documentos que tengan un | |
projectionobjectDefault: {} | Una proyección de MongoDB que App Services fusiona con la proyección existente de una operación filtrada. ImportanteConflictos de proyecciónLas proyecciones de MongoDB pueden ser inclusivas o exclusivas; es decir, pueden devolver solo los campos especificados o excluir los campos no especificados. Si se aplican varios filtros a una consulta, todos deben especificar el mismo tipo de proyección; de lo contrario, la consulta fallará. EjemploUn filtro retiene el campo |
Nota
Consideraciones de seguridad para los filtros de servicios de aplicaciones
Aunque los permisos basados en roles y los filtros pueden ocultar documentos y campos específicos dentro de una colección, existe la posibilidad de que los datos puedan ser expuestos si el sistema permite ejecutar queries para acceder a la colección.
Por ejemplo, las queries o funciones que provocan errores dependiendo de los valores almacenados en una colección (como los errores de división por cero) pueden revelar información sobre documentos, incluso si un rol o filtro impide que el usuario que realiza la query vea los documentos directamente. Los usuarios también pueden hacer inferencias sobre los datos subyacentes de otras maneras (como midiendo el tiempo de ejecución de la query, que puede verse afectado por la distribución de los datos).
Tenga en cuenta que esto es posible y audite sus patrones de acceso a datos cuando sea necesario.