Overview
A filter modifies an incoming MongoDB query to return only a subset of the results matched by the query. Adding a filter to a collection allows you to control the shape of queried documents and can improve query performance.
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:
A query on a collection.
Un guardar en un documento.
A filter applies to a given request if its "apply when" expression evaluates to true given that request's context. If a filter applies to a request, App Services merges the filter's query or projection into the requested operation's existing query and projection.
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 |
|---|---|---|
|
|
|
Define Filters
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.
Considera usar filtros si se desea un sistema centralizado para:
Restringir las consultas a un subconjunto de todos los documentos
Omitir datos confidenciales o campos no utilizados
Ejemplo
In a voting app where some users have agreed to anonymously share their vote, you could use the following filter to constrain all queries to an anonymous subset of the existing data:
{ "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
Puedes definir filtros para colecciones específicas en tu clúster vinculado desde la Interfaz de usuario Realm o implementando archivos de configuración con Realm CLI:
Nota
This guide requires a linked MongoDB Atlas data source.
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, especifica un documento que contenga predicados de query adicionales que se fusionarán en la query entrante cuando se aplique el filtro. Por ejemplo, un filtro que retenga documentos que tengan un score por debajo de 20 podría utilizar la siguiente query 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 regla
Para definir o modificar roles en una colección, abre el archivo de configuración rules.json dentro del directorio de configuración de la colección.
Tip
Scaffold the Collection
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
This guide focuses on creating filters for the collection. Check out the other configuration guides to learn how to define roles and permissions and enforce schemas.
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 | Requerido. El nombre del filtro. Los nombres de filtro son útiles para identificar y diferenciar los filtros. Limitado a 100 caracteres o menos. | |
apply_whenobject | An expression that determines when this filter applies to an incoming MongoDB operation. 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ónMongoDB projections can be either inclusive or exclusive, i.e. they can either return only specified fields or withhold fields that are not specified. If multiple filters apply to a query, the filters must all specify the same type of projection, or the query will fail. EjemploA filter withholds the |
Nota
Security Consideration for App Services Filters
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.