Sobre las Consultas

Este documento proporciona instrucciones detalladas sobre cómo usar filtros de consulta en varios endpoints de listado dentro del servicio de ledger. Los filtros permiten delimitar registros de forma precisa según los criterios del solicitante de la API. Aunque están inspirados en MongoDB, la sintaxis de filtrado no está relacionada con la base de datos subyacente utilizada por el ledger. Los filtros se implementan a través de parámetros de consulta (query parameters).

Endpoints Soportados

El filtrado se aplica a todos los endpoints que devuelven listas de registros, como /intents, /wallets, y otros.

Operadores de Consulta

Actualmente, se admiten los siguientes operadores de consulta:

Sintaxis de Filtrado

Los filtros se pasan como parámetros de consulta con el siguiente patrón:
some.field.path.$operator=value Si no se especifica ningún operador, se asume $eq (igual).

La ruta del campo refleja la estructura de la respuesta de la API para ese tipo de registro. Por ejemplo, si un intent tiene una propiedad data que contiene un string handle, el filtro para handle será data.handle.

Cuando se especifican múltiples filtros, todas las condiciones deben cumplirse para que un registro se incluya en la respuesta.

GET /v2/intents?data.handle.$eq=my-intent
# estos dos llamados son equivalentes
GET /v2/intents?data.handle=my-intent

El filtro anterior coincidirá con intents donde data.handle es igual a my-intent.

GET /v2/intents?data.schema.$eq=business-wallet

El filtro anterior coincidirá con billeteras cuyo schema es business-wallet.

GET /v2/wallet?meta.status.$eq=active

El filtro anterior coincidirá con billeteras que están marcadas como activas.

Uso de Filtros con el SDK

El SDK de Ledger admite filtros de consulta con typings para autocompletado y verificación de tipos. Ejemplo:

const { wallets, response, page } = await sdk.wallet.list({
    page: {
        index: 0,
        limit: 10,
    },
    'meta.moment.$gt': new Date('2021-01-01T00:00:00Z'),
});

const { wallets, response, page } = await sdk.wallet.list({
    page: {
        index: 0,
        limit: 10,
    },
    'data.claims.$eq': [
        {
            action: 'transfer',
            amount: 1000,
            source: 'source',
            target: 'target',
            symbol: 'cop',
        },
    ],
});

Filtrado de Arreglos

Para propiedades tipo arreglo como claims en intents, se pueden aplicar dos tipos de filtrado:

1. Filtrado por Índice Específico

   GET /v2/intents?data.claims.0.amount.$gt=20

   Coincide con intents donde el monto de la primera claim es mayor a 20. Ejemplo equivalente en el SDK:

   const { wallets, response, page } = await sdk.wallet.list({
   page: {
       index: 0,
       limit: 10,
   },
   "data.claims.0.amount.$gt": 20,
   
   });

2. Filtrado por Cualquier Elemento

   GET /v2/intents?data.claims.amount.$gt=20

   Coincide con intents donde cualquier claim tiene un monto mayor a 20. Ejemplo equivalente en el SDK:

   const { wallets, response, page } = await sdk.wallet.list({
       page: {
           index: 0,
           limit: 10,
       },
       'data.claims.amount.$gt': 20,
   });

Limitaciones Conocidas

• Algunos campos pueden no ser filtrables en ciertos tipos de registro. Si se consulta un campo no soportado, un error especificará cuáles son los campos no admitidos.
• Actualmente, ciertos filtros se procesan en memoria. Las futuras versiones optimizarán el rendimiento al manejar más operaciones de filtrado dentro de la base de datos.
• Las consultas están limitadas a parámetros de consulta en endpoints GET. Debido a las restricciones de sintaxis, los operadores $and y $or aún no son compatibles;
  todos los filtros se combinan de forma implícita con un $and. Las futuras actualizaciones podrían introducir endpoints POST para admitir expresiones de filtro más complejas.