/companies/search, /people/search, /companies/advertisements/search) comparten un único motor de filtros. Compones el cuerpo de la solicitud una vez y las mismas reglas se aplican en todos los endpoints — incluida la forma en que se combinan los filtros multivalor, cómo se comparan las ubicaciones y cómo anulas el operador por defecto con filter_conditions.
¿Por qué un motor de filtros unificado?
Un esquema, tres endpoints
Los filtros a nivel de empresa como
technologies, verticals y founded_dates funcionan de forma idéntica en /companies/search, /people/search y dentro de company_filters de Monitor — los aprendes una sola vez.AND/OR por filtro
El valor por defecto es OR (coincide con cualquiera). Promueve filtros individuales a AND (coincide con todos) agregando una entrada a
filter_conditions — sin tocar el resto del cuerpo.Operadores nativos de Postgres
Los filtros de array se compilan a operadores nativos de Postgres —
&& (solapamiento) para OR, @> (contiene) para AND. Compatibles con índices, sin post-filtrado del lado de la aplicación.Los mismos filtros en Monitores
El bloque
company_filters en Monitores acepta la misma forma, por lo que un payload de búsqueda que funciona también funciona como payload de monitor.Anatomía de una solicitud de búsqueda
Cada solicitud de búsqueda se construye a partir de tres capas en el mismo cuerpo JSON:
Una solicitud mínima a
/people/search que usa las tres capas:
company_filters: mantén agrupadas las claves de nivel de empresa
El objeto contenedor company_filters: {...} es la forma recomendada de enviar filtros a nivel de empresa — separa visualmente qué claves filtran a la persona de cuáles filtran a la empresa, y coincide con la forma que ya usan los Monitores, de modo que los payloads se transfieren limpiamente entre configuraciones de búsqueda y de monitor.
Ambos estilos funcionan; el motor aplana la forma envuelta al nivel superior antes de procesar, y las claves de nivel superior ganan en caso de conflicto:
filter_conditions para una clave de nivel de empresa, colócala dentro de company_filters para que viaje junto con las claves que anula.
Misma forma en las variantes /search/similar
POST /companies/search/similar y POST /people/search/similar aceptan el mismo cuerpo de filtros que sus contrapartes sin “similar” (incluyendo el contenedor company_filters y filter_conditions). Cada uno agrega un paso de similitud adicional:
El sobre de la respuesta es, por lo demás, idéntico al del endpoint estándar
search. Los filtros acotan el conjunto de candidatos antes de que se aplique la clasificación por similitud — por lo que combinar company_locations: ["US"] con /people/search/similar devuelve a las personas con sede en EE. UU. más cercanas a tus títulos de referencia, que es el patrón “encuentra más personas como X dentro de estas restricciones”.
A diferencia de los endpoints estándar
/search, /search/similar no devuelve un pagination.total_entries exacto — el valor tiene un tope porque la búsqueda por similitud clasifica los resultados por relevancia y solo muestra las mejores coincidencias. Usa la búsqueda por similitud para encontrar las mejores coincidencias, no para enumerar cada una de ellas.AND frente a OR — la única decisión que tomas por filtro
Los filtros multivalor (technologies, verticals, keywords, categories, …) aceptan un array. El operador decide qué significa “coincidencia”:
- OR (por defecto)
- AND
Coincide con cualquier valor. Devuelve filas cuyo array se solapa con la entrada.Una empresa se incluye si su stack tecnológico contiene al menos uno de
Python, PostgreSQL o Kubernetes. Se compila a column && ARRAY[...] en Postgres.Úsalo cuando: quieres un alcance amplio — “interesado en cualquiera de estos”, “ubicado en cualquiera de estos países”.Los filtros no listados en
filter_conditions usan el operador por defecto (OR dentro de un array, AND entre claves de filtro distintas). Solo declaras las anulaciones — nunca los valores por defecto.Qué puedes anular
Cada endpoint acepta anulaciones para un conjunto de claves distinto. Las claves provienen del enum de OpenAPI en cada esquema*_filter_conditions:
Endpoint de empresas
Claves de
company_filter_conditions: keywords, verticals, vertical_categories, vertical_sub_categories, technologies, categories, advertisement_target_locations, advertisement_exclude_target_locations, advertisement_search_terms, places, exclude_places, job_exclude_locations.Endpoint de personas
Claves de
people_filter_conditions (delegan al motor de empresa): keywords, verticals, vertical_categories, vertical_sub_categories, technologies, categories, places, exclude_places, además de social_media.Endpoint de anuncios
Claves de
ads_filter_conditions: target_locations, exclude_target_locations. Conjunto más pequeño porque los anuncios solo se filtran por país de impresión.Consejos de rendimiento
Filtra primero por columnas indexadas
Filtra primero por columnas indexadas
Las ubicaciones, los rangos de empleados y
founded_dates están indexados y reducen el conjunto de candidatos más rápido que los filtros de texto libre o de vertical. Combínalos con uno o dos filtros precisos antes de recurrir a la búsqueda por similitud.No abuses de AND en arrays grandes
No abuses de AND en arrays grandes
column @> ARRAY[a, b, c, …] exige que cada valor esté presente. La cardinalidad crece rápido — un AND de 10 tecnologías en una categoría con un promedio de 3 etiquetas tecnológicas devuelve casi cero filas y fuerza un escaneo completo. Prefiere entre 2 y 4 valores por filtro AND; cambia a OR para consultas exploratorias.Usa is_enable_similarity_search para entradas de texto libre
Usa is_enable_similarity_search para entradas de texto libre
Si no puedes proporcionar IDs de slug (verticales, tecnologías, categorías) y solo tienes cadenas de texto libre, configura
is_enable_similarity_search: true y similarity_score: 0.7. El motor resuelve las coincidencias antes de aplicar el filtro — mucho más económico que escanear texto.Prefiere rangos sobre listas de enum para tamaño e ingresos
Prefiere rangos sobre listas de enum para tamaño e ingresos
employees: [[201, 500], [501, 1000]] (un array de rangos) y revenues: [1000000, 5000000] (un único rango mínimo/máximo) son más rápidos y más idiomáticos que listas largas de IDs.Filtros de actividad publicitaria
/companies/search puede filtrar por la huella publicitaria de una empresa — cuántos anuncios ejecuta, si alguno está actualmente activo, qué plataformas y formatos usa, y cómo se clasifica frente a otros anunciantes en un país determinado. POST /companies/advertisements/search también acepta todos estos filtros (advertisement_active_ads, advertisement_running_ads, advertisement_total_ads, advertisement_platform_count, advertisement_format_count, advertisement_impressions_estimate, advertisement_formats, advertisement_country_activity) — un anuncio se incluye si la empresa propietaria cumple el límite.
Usa
null para un límite abierto — [1, null] significa “al menos 1”, [null, 500] significa “500 o menos”.
Clasificación dentro de un país
advertisement_country_activity acota el rango, el percentil y la puntuación de volumen a un país a la vez — el rango publicitario de una empresa en EE. UU. no dice nada sobre su rango en Alemania, por lo que country es obligatorio:
advertisement_country_activity con los filtros de todos los países anteriores en la misma solicitud — por ejemplo, “clasificado en el top 500 en EE. UU., y tiene al menos 100 anuncios activos a nivel de empresa”:
Próximos pasos
filter_conditions
Página de referencia — cada clave admitida, cada valor por defecto, y recetas AND/OR copiables.
Personas + Filtros de empresa
Usa cualquier filtro de empresa dentro de
/people/search. La función destacada del motor unificado.Referencia de Company Search
Esquema completo de solicitud/respuesta para
/companies/search.Referencia de People Search
Esquema completo de solicitud/respuesta para
/people/search.¿Buscas el recorrido de filtrado del lado del dashboard? Consulta Filtrar y exportar contactos en la Base de conocimiento.