# Sintaxis de consultas (/es/docs/developer/query-syntax)

Elige el formato de filtro para la superficie que uses. MCP usa filtros estructurados. La barra de búsqueda web y algunos campos REST aceptan texto de filtro.

## De un vistazo [#de-un-vistazo]

| Superficie | Entrada de filtro |
| --- | --- |
| Búsqueda web | Texto DSL de Operations en la barra de búsqueda o `?f=` |
| Lista de acciones REST | `fullFilter` para el DSL de Operations completo |
| Búsqueda de conversaciones REST | `filter` para el DSL de búsqueda avanzada |
| Campos heredados de lista de acciones REST | `filter` / `filterJson`: solo el indicador de respondido |
| Búsqueda y analíticas MCP | Árbol `filter` estructurado; sin cadena DSL |
| Campos específicos de la organización | Descúbrelos antes de usarlos |

## Qué estás viendo [#qué-estás-viendo]

Un filtro selecciona registros. Su vocabulario de campos depende de la fuente de datos.
No copies un campo REST en MCP ni asumas que una fuente acepta el filtro de otra fuente.

## Texto de filtro [#texto-de-filtro]

| Patrón | Significado |
| --- | --- |
| `field=value`, `field!=value` | Igual o diferente |
| `field>value`, `field>=value`, `field<value`, `field<=value` | Comparación |
| `field~value`, `field!~value` | Contiene o no contiene |
| `field^=value`, `field$=value` | Empieza con o termina con |
| `field=min..max` | Rango |
| `field=v1,v2` | Cualquier valor listado |
| `expr1+expr2` | AND |
| `expr1\|expr2` | OR |
| `(expr)` | Grupo |

Usa estos patrones solo donde ese endpoint acepta la gramática.
Un ejemplo para la lista de acciones REST es `fullFilter=src=TWITTER+kw~refund`.
Usa codificación URL para preservar los operadores y el texto literal. `--data-urlencode` lo maneja en curl.

## Filtros heredados de lista de acciones [#filtros-heredados-de-lista-de-acciones]

`GET /v0/action/list?filter=ro=true` selecciona acciones respondidas.
`filter=ro=false` elimina esa restricción de respondido. El valor predeterminado son las acciones respondidas.
Los campos heredados `filter` y `filterJson` no aplican condiciones de plataforma, cola, estado u otras.
Usa `fullFilter` para esas condiciones. No lo combines con un campo de filtro heredado.

En el DSL de Operations completo, `ro` significa registro raíz, no respondido.
Usa el campo de respondido declarado cuando te refieras a una respuesta de agente.

## Filtros estructurados de MCP [#filtros-estructurados-de-mcp]

Lee `sift.spec("query.search.actions")` antes de una nueva búsqueda.
Envía un árbol en el campo `filter` de la operación:

```json
{
  "filterType": "and",
  "filters": [
    { "filterType": "source", "operator": "in", "value": ["TWITTER"] },
    { "filterType": "status", "operator": "in", "value": ["OPEN"] }
  ]
}
```

Los grupos usan `filterType` (`and` u `or`) y `filters`.
Las hojas usan un `filterType` compatible, un `operator` y un `value` con el tipo correcto.
Por ejemplo, las comparaciones de listas usan arreglos; las comparaciones booleanas usan booleanos.
Una hoja de campo personalizado también nombra su campo registrado.

## Fechas y descubrimiento de campos [#fechas-y-descubrimiento-de-campos]

Establece `dateRange` y `time.timezone` explícitamente cuando la tarea depende de fechas.
Consulta la referencia de campos para las reglas de fecha de fin inclusiva o exclusiva de la superficie.
Para un campo personalizado, llama a `query.search.custom_fields` mediante `execute`; para una dimensión desconocida, lee `sift.spec("query.analytics.<source>")`.
Usa el nombre de campo y los operadores devueltos. Lee los valores de la lista de valores del campo (`query.search.<list>`). No adivines un campo personalizado a partir de una etiqueta de visualización.

## Consejos [#consejos]

- Mantén los filtros fijos mientras sigues un cursor.
- Una consulta no válida falla con cada problema y los valores válidos más cercanos. Una primera página vacía incluye `emptyReason`.
- Verifica los resultados vacíos antes de eliminar un filtro.
- Usa analíticas para totales en lugar de contar páginas de búsqueda.

Consulta el [Diccionario de campos de registros](/docs/developer/record-fields) para entender `pmid`, `prid`, otras claves cortas y los campos anidados de los resultados.

## Relacionado [#relacionado]

<Cards>
  <Card href="/docs/developer/mcp-reference" title="Referencia de campos MCP">Filtros de fuente, fechas y resultados vacíos.</Card>
  <Card href="/docs/developer/api-reference" title="Referencia de campos API">Campos de consulta REST y paginación.</Card>
  <Card href="/docs/developer/agent-guide" title="Guía de agente">Usa filtros en recetas prácticas.</Card>
</Cards>