Filtrar filas usando OData

Artículo
08/05/2024

Utilice la $filter opción de consulta para filtrar una colección de recursos.

Dataverse evalúa cada recurso de la colección mediante el conjunto de expresiones para $filter. Solo se devuelven en la respuesta los registros en los que la expresión se evalúa como true. Los registros no se devuelven si la expresión se evalúa como false o null, o si el usuario no tiene acceso de lectura al registro.

La siguiente tabla describe los operadores y funciones que puede usar en expresiones $filter.

	Descripción	Más información
Operadores de comparación	Use los operadores `eq`,`ne`,`gt`,`ge`,`lt`, y `le` para comparar una propiedad y un valor.	Operadores de comparación
Operadores lógicos	Use `and`, `or` y `not` para crear expresiones más complejas.	Operadores lógicos
Agrupación de operadores	Utilice paréntesis: `()`, para especificar la precedencia para evaluar una expresión compleja.	Agrupación de operadores
Funciones de consulta de OData	Evaluar valores de cadena usando las funciones `contains`, `endswith` y `startswith`	Usar funciones de consulta de OData
Funciones de consulta de Dataverse	Utilice más de 60 funciones especializadas diseñadas para aplicaciones comerciales.	Funciones de consulta de Dataverse
Expresiones Lambda	Cree expresiones basadas en valores de colecciones relacionadas.	Filtrar usando valores de colecciones relacionadas

Operadores de comparación

La siguiente tabla describe los operadores que puede usar para comparar una propiedad y un valor.

Operator	Descripción	Ejemplo
`eq`	Es igual a	`$filter=revenue eq 100000`
`ne`	No es igual a	`$filter=revenue ne 100000`
`gt`	Mayor que	`$filter=revenue gt 100000`
`ge`	Mayor o igual que	`$filter=revenue ge 100000`
`lt`	Menor que	`$filter=revenue lt 100000`
`le`	Menor o igual que	`$filter=revenue le 100000`

Comparación de columnas

Puede utilizar operadores de comparación para comparar valores de propiedad en la misma fila. Solo se pueden usar operadores de comparación para comparar valores en la misma fila, y los tipos de columna deben coincidir. Por ejemplo, la siguiente consulta devuelve todos los contactos donde firstname es igual a lastname:

GET [Organization URI]/api/data/v9.2/contacts?$select=fullname&$filter=firstname eq lastname

Operadores lógicos

La siguiente tabla describe los operadores lógicos que puede usar para crear expresiones más complejas.

Operator	Descripción	Ejemplo
`and`	Lógico y	`$filter=revenue lt 100000 and revenue gt 2000`
`or`	Disyunción lógica	`$filter=contains(name,'(sample)') or contains(name,'test')`
`not`	Negación lógica	`$filter=not contains(name,'sample')`

Agrupación de operadores

Utilice paréntesis () con operadores lógicos para especificar la precedencia para evaluar una expresión compleja; por ejemplo:

$filter=(contains(name,'sample') or contains(name,'test')) and revenue gt 5000

Funciones de consulta de Dataverse

Utilice más de 60 funciones especializadas diseñadas para aplicaciones comerciales. Estas funciones proporcionan capacidades especiales, como se describe en la siguiente tabla.

Grupo	Funciones
Fechas	InFiscalPeriod, InFiscalPeriodAndYear, InFiscalYear, InOrAfterFiscalPeriodAndYear, InOrBeforeFiscalPeriodAndYear, Last7Days, LastFiscalPeriod, LastFiscalYear, LastMonth, LastWeek, LastXDays, LastXFiscalPeriods, LastXFiscalYears, LastXHours, LastXMonths, LastXWeeks, LastXYears, LastYear, Next7Days, NextFiscalPeriod, NextFiscalYear, NextMonth, NextWeek, NextXDays, NextXFiscalPeriods, NextXFiscalYears, NextXHours, NextXMonths, NextXWeeks, NextXYears, NextYear, OlderThanXDays, OlderThanXHours, OlderThanXMinutes, OlderThanXMonths, OlderThanXWeeks, OlderThanXYears, On, OnOrAfter, OnOrBefore, ThisFiscalPeriod, ThisFiscalYear, ThisMonth, ThisWeek, ThisYear, Today, Tomorrow, Yesterday
Valores de id.	EqualBusinessId, EqualUserId, NotEqualBusinessId, NotEqualUserId
Jerarquía	Above, AboveOrEqual, EqualUserOrUserHierarchy, EqualUserOrUserHierarchyAndTeams, EqualUserOrUserTeams, EqualUserTeams, NotUnder, Under, UnderOrEqual Más información: Consulta de datos jerárquicos
Columnas de elecciones	ContainValues, DoesNotContainValues Más información: Consultar datos de opciones
Entre	Between, NotBetween
En	In, NotIn
Lenguaje	EqualUserLanguage

Nota

La funcioń Contains es para usar con columnas que tienen indexación de texto completo. Solo la tabla Dynamics 365 KBArticle (artículo) tiene columnas que tienen indexación de texto completo. Use en su lugar la función contains de OData.

Web API Query Function Reference tiene la lista completa. Cada artículo proporciona un ejemplo de sintaxis que puede copiar.

Debe utilizar el nombre completo de la función y agregar el espacio de nombres de servicio (Microsoft.Dynamics.CRM) al nombre de la función.

Cada función tiene un parámetro PropertyName que especifica la propiedad a evaluar. La función puede tener más parámetros, como PropertyValue, PropertyValues o PropertyValue1 y PropertyValue2. Cuando existen estos parámetros, debe proporcionar un valor o valores para comparar con el parámetro PropertyName.

El siguiente ejemplo muestra los usos de la función Between para buscar cuentas con entre 5 y 2000 empleados.

GET [Organization URI]/api/data/v9.2/accounts?$select=name,numberofemployees
&$filter=Microsoft.Dynamics.CRM.Between(PropertyName='numberofemployees',PropertyValues=["5","2000"])

Filtrar usando valores de cadena

Tenga en cuenta los siguientes puntos cuando filtre valores de cadena:

Todos los filtros que usen valores de cadena distinguen mayúsculas de minúsculas.
Debe codificar como URL los caracteres especiales en los criterios de filtro. Más información: codificar caracteres especiales de URL
Puedes utilizar caracteres comodín, pero evita utilizarlos incorrectamente. Más información: Uso de caracteres comodín
Puede utilizar las funciones de consulta de OData: contains, startswith y endswith. Más información: Usar las funciones de consulta de OData
Debe administrar comillas simples cuando use filtros que acepten una matriz de valores de cadena. Más información: Administrar comillas simples

URL codifica los caracteres especiales

Si la cadena que está utilizando como valor en una función de filtro incluye un carácter especial, debe codificarlo como URL. Por ejemplo, si usa esta función: contains(name,'+123'), no funcionará porque + es un carácter que no se puede incluir en una URL. Si codifica la cadena como URL, se convertirá en contains(name,'%2B123') y obtendrá resultados donde el valor de la columna contiene +123.

La siguiente tabla muestra los valores codificados de URL para caracteres especiales comunes.

Especial carácter	URL de codificación carácter
`$`	`%24`
`&`	`%26`
`+`	`%2B`
`,`	`%2C`
`/`	`%2F`
`:`	`%3A`
`;`	`%3B`
`=`	`%3D`
`?`	`%3F`
`@`	`%40`

Usar caracteres comodín

Al componer filtros usando cadenas, puede aplicar los siguientes caracteres comodín:

Caracteres	Descripción	Documentación y ejemplos de T-SQL
`%`	Coincide con cualquier cadena de cero o más caracteres. Este carácter comodín se puede utilizar como prefijo o como sufijo.	Carácter de porcentaje (Comodín - Caracteres que deben coincidir) (Transact-SQL)
`_`	Utilice el carácter de subrayado para hacer coincidir cualquier carácter único en una operación de comparación de cadenas que implique la coincidencia de patrones.	_ (Comodín - Coincidir con un carácter) (Transact-SQL)
`[]`	Hace que coincida con cualquier carácter único dentro del rango o conjunto especificado que se especifica entre paréntesis.	[ ] (Comodín - Coincidir con caracteres) (Transact-SQL)
`[^]`	Hace que coincida con cualquier carácter único que no esté dentro del rango o conjunto especificado que se especifica entre paréntesis cuadrados.	[^] (Comodín - Los caracteres no coinciden) (Transact-SQL)

Más información: Utilice caracteres comodín en las condiciones para los valores de cadena

No se admiten comodines iniciales

Es importante no utilizar el comodín inicial Tarjetas porque no son compatibles. Las consultas que utilizan estos antipatrones presentan problemas de rendimiento porque las consultas no se pueden optimizar. A continuación se muestran algunos ejemplos de comodines principales:

startswith(name,'%value')
endswith(name,'value%')

Obtenga más información sobre los errores que se devuelven cuando se utilizan comodines iniciales

Usar funciones de consulta de OData

La siguiente tabla describe las funciones de consulta de OData que puede usar para filtrar valores de cadena:

Function	Ejemplo
`contains`	`$filter=contains(name,'(sample)')`
`endswith`	`$filter=endswith(name,'Inc.')`
`startswith`	`$filter=startswith(name,'a')`

Puede usar estas funciones con el operador lógico not para negar el resultado.

Administrar comillas simples

Algunos filtros aceptan una matriz de valores de cadena, como la función In Query. Al especificar valores en estos filitros que contienen una comilla o apóstrofo, como O'Brian o Men's clothes, debe usar comillas dobles alrededor de los valores, por ejemplo:

GET [Organization URI]/api/data/v9.2/contacts?$select=fullname
&$filter=Microsoft.Dynamics.CRM.In(PropertyName=@p1,PropertyValues=@p2)
&@p1='lastname'
&@p2=["OBrian","OBryan","O'Brian","O'Bryan"]

Si no lo hace, obtiene el siguiente error:Invalid JSON. A comma character ',' was expected in scope 'Array'. Every two elements in an array and properties of an object must be separated by commas.

Si el filtro es para un solo valor, reemplace el carácter de comilla simple con dos caracteres de comilla simple consecutivos; por ejemplo:

GET [Organization URI]/api/data/v9.2/contacts?$select=fullname
&$filter=lastname eq 'O''Bryan'

Si no lo hace, obtiene un error como este: There is an unterminated literal at position 21 in 'lastname eq 'O'Bryan''.

Puede filtrar las filas devueltas en función de los valores de las tablas relacionadas. La forma de filtrar depende del tipo de relación.

Filtrar por propiedad de búsqueda

Para Relaciones de uno a muchos, una colección filtrada devuelve los mismos resultados que usar una eq $filter en la propiedad de búsqueda para la relación. Por ejemplo, esta colección filtrada:

GET [Organization URI]/api/data/v9.2/systemusers(<systemuserid value>)/user_accounts?$select=name

Es lo mismo que este filtro en una propiedad de búsqueda.

GET [Organization URI]/api/data/v9.2/accounts?$filter=_owninguser_value eq <systemuserid value>&$select=name

Filtrar usando valores de propiedad de columna de búsqueda

Puede filtrar según los valores de las propiedades de navegación de valor único que representan columnas de búsqueda. Use este patrón:

<single-valued navigation property>/<property name>

El siguiente ejemplo devuelve registros de cuentas en función del valor de la columna primarycontactid/fullname:

Solicitud:

GET [Organization URI]/api/data/v9.2/accounts?$filter=primarycontactid/fullname eq 'Susanna Stubberod (sample)'
&$select=name,_primarycontactid_value
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Respuesta:

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Preference-Applied: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,_primarycontactid_value)",
    "value": [
        {
            "@odata.etag": "W/\"81359849\"",
            "name": "Litware, Inc. (sample)",
            "_primarycontactid_value@OData.Community.Display.V1.FormattedValue": "Susanna Stubberod (sample)",
            "_primarycontactid_value": "70bf4d48-34cb-ed11-b596-0022481d68cd",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd"
        }
    ]
}

También puede comparar valores más arriba en la jerarquía de propiedades de navegación de valor único.

El siguiente ejemplo devuelve la primera cuenta donde el registro de contacto representa primarycontactid, donde 'System Administrador' creó el registro, usando primarycontactid/createdby/fullname en el $filter.

Solicitud:

GET [Organization URI]/api/data/v9.2/accounts?$filter=primarycontactid/createdby/fullname eq 'System Administrator'
&$select=name,_primarycontactid_value
&$expand=primarycontactid(
$select=fullname,_createdby_value;
$expand=createdby($select=fullname))
&$top=1
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Respuesta:

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Preference-Applied: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,_primarycontactid_value,primarycontactid(fullname,_createdby_value,createdby(fullname)))",
    "value": [
        {
            "@odata.etag": "W/\"81359849\"",
            "name": "Litware, Inc. (sample)",
            "_primarycontactid_value@OData.Community.Display.V1.FormattedValue": "Susanna Stubberod (sample)",
            "_primarycontactid_value": "70bf4d48-34cb-ed11-b596-0022481d68cd",
            "accountid": "78914942-34cb-ed11-b596-0022481d68cd",
            "primarycontactid": {
                "fullname": "Susanna Stubberod (sample)",
                "_createdby_value@OData.Community.Display.V1.FormattedValue": "System Administrator",
                "_createdby_value": "4026be43-6b69-e111-8f65-78e7d1620f5e",
                "contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd",
                "createdby": {
                    "fullname": "System Administrator",
                    "systemuserid": "4026be43-6b69-e111-8f65-78e7d1620f5e",
                    "ownerid": "4026be43-6b69-e111-8f65-78e7d1620f5e"
                }
            }
        }
    ]
}

Utilice los operadores Lambda any y all para evaluar valores en una colección para filtrar los resultados.

any: devuelve true si la expresión booleana aplicada es true para cualquier miembro de la colección; si no, devuelve false.
- El operador any sin un argumento devuelve true si la colección no está vacía.
all: devuelve true se la expresión booleana aplicada es true todos los miembros de la colección; si no, devuelve false.

La sintaxis tiene el siguiente aspecto:

<collection>/[any | all](o:<expression to evaluate>)

En este caso, o es la variable que representa los elementos de la colección. La convención es usar la primera letra del tipo. En la expresión, utilice o/<property or collection name> para hacer referencia a una propiedad o colección de un elemento determinado.

Puede incluir condiciones en varias propiedades de navegación con valores de colección y colecciones anidadas. No puede incluir condiciones en las propiedades de navegación con valores de colección que están anidadas en una propiedad de navegación de búsqueda. Por ejemplo, $filter=primarycontactid/new_contact_account/any(a:a/accountid eq '{GUID}') no se admite.

Más información: Usar operadores Lambda en odata.org

Ejemplos de operadores Lambda

El siguiente ejemplo recupera todos los registros de cuentas que tienen al menos un correo electrónico con "sometext" en el asunto:

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=Account_Emails/any(e:contains(e/subject,'sometext'))
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

El siguiente ejemplo recupera todos los registros de cuentas que tienen todas las tareas asociadas cerradas:

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=Account_Tasks/all(t:t/statecode eq 1)
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

El siguiente ejemplo recupera todos los registros de cuentas que tienen al menos un correo electrónico con "sometext" en el asunto y cuyo código de estado está activo:

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=Account_Emails/any(e:contains(e/subject,'sometext') and 
e/statecode eq 0)
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

El siguiente ejemplo crea una consulta anidada usando los operadores any y all:

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=(contact_customer_accounts/any(c:c/jobtitle eq 'jobtitle' and 
c/opportunity_customer_contacts/any(o:o/description ne 'N/A'))) and 
endswith(name,'Inc.')
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Límites de las condiciones

No puede incluir más de 500 condiciones en total en una consulta. De lo contrario, verá este error:

Nombre: TooManyConditionsInQuery
Código: 0x8004430C
Número: -2147204340
Mensaje: Number of conditions in query exceeded maximum limit.

Debe reducir la cantidad de condiciones para ejecutar la consulta. Es posible reducir la cantidad de condiciones utilizando las funciones de consulta In o NotIn , que se pueden usar con números, identificadores únicos y cadenas de hasta 850 caracteres.

Pasos siguientes

Aprenda a paginar resultados.

Resultados de página

Nota

¿Puede indicarnos sus preferencias de idioma de documentación? Realice una breve encuesta. (tenga en cuenta que esta encuesta está en inglés)

La encuesta durará unos siete minutos. No se recopilan datos personales (declaración de privacidad).

Compartir a través de

Filtrar filas usando OData

Operadores de comparación

Comparación de columnas

Operadores lógicos

Agrupación de operadores

Funciones de consulta de Dataverse

Filtrar usando valores de cadena

URL codifica los caracteres especiales

Usar caracteres comodín

No se admiten comodines iniciales

Usar funciones de consulta de OData

Administrar comillas simples

Filtrar por propiedad de búsqueda

Filtrar usando valores de propiedad de columna de búsqueda

Ejemplos de operadores Lambda

Límites de las condiciones

Pasos siguientes

Recursos adicionales

Compartir a través de

Filtrar filas usando OData

Operadores de comparación

Comparación de columnas

Operadores lógicos

Agrupación de operadores

Funciones de consulta de Dataverse

Filtrar usando valores de cadena

URL codifica los caracteres especiales

Usar caracteres comodín

No se admiten comodines iniciales

Usar funciones de consulta de OData

Administrar comillas simples

Filtrar en función de los valores de datos relacionados

Filtrar por propiedad de búsqueda

Filtrar usando valores de propiedad de columna de búsqueda

Filtrar usando valores de colecciones relacionadas

Ejemplos de operadores Lambda

Límites de las condiciones

Pasos siguientes

Recursos adicionales