Getting started with Search
You can use Search to retrieve any data — ledgers, ledger balances, and transactions — from your Blnk Ledger.
In this guide, you’ll learn the basics of sending search queries to Blnk and how we return responses.
1. Using Search
Use the search endpoint URL
POST http://YOUR_URL/search/:collection
:collection refers to the collection of data you want to query. There are currently only 3 collections in Blnk:
- Ledgers (
/search/ledgers). - Ledger balances (
/search/balances). - Transactions (
/search/transactions).
Input your search query
Send a request payload containing your search query.
Consider the following example, a POST request to /search/balances:
{
"q": "*",
"filter_by": "balance:>1000",
"sort_by": "created_at:desc",
"page": 2,
"per_page": 50
}
| Field | Description | Required | Example |
|---|---|---|---|
q | The query text to search for in the collection. Learn more about querying. | Yes | "*" returns all records in the transaction. |
filter_by | Filter conditions for refining your results. | No | balance:>1000 returns all ledger balances with their balance value greater than “1000.” |
sort_by | Sorting conditions that will be used to order your results. | No | created_at:desc orders the results in by the “created_at” field in descending order. |
page | The page number of your results. | No | 2 returns the second page of the results. |
per_page | The number of results per page. | No | 50 returns only 50 results on one page; to see the rest (if any), you’ll need to move to the next page. |
Your query is processed and the results are presented in the following response format:
{
"found": 1,
"out_of": 1,
"page": 1,
"request_params": {
"q": "*",
"filter_by": "balance:>1000",
"sort_by": "created_at:desc",
"page": 2,
"per_page": 50
},
"search_time_ms": 1,
"hits": [
{
"document": {
"balance_id": "bln_0be360ca-86fe-457d-be43-daa3f966d8f0",
"balance": 0,
"credit_balance": 0,
"debit_balance": 0,
"currency": "USD",
"precision": 1,
"ledger_id": "ldg_073f7ffe-9dfd-42ce-aa50-d1dca1788adc",
"created_at": "2024-02-20 05:28:03 UTC",
"meta_data": null
}
}
]
}
| Field | Description |
|---|---|
found | Number of documents that match your search query and filtering conditions. |
out_of | Number of documents that match only your search query. |
page | The page being displayed to you. |
request_params | Your request payload. |
search_time_ms | Time it took for the search query to execute, usually in ms. |
hits | Contains an array of your search results. |
document | Represents the actual search result item. |
2. Understanding search query
Structure and terminology
A query clause consists of a field followed by an operator and then a value.
| Terms | Example | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| clause | "q": "*" | |||||||||
| field | "q" | |||||||||
| operator | : | |||||||||
| value | "*" |
Quotes
You must always use quotation marks around string values in your query. You can omit them for numerical values.
"filter_by": "balance:>1000"means quotes are required because the value is a string."per_page": 50doesn’t need quotes because it is a numerical value.
3. Supported parameters
The parameters you can specify in the value part of your query clause are determined by the collection you are searching in.
There are three data collections in the current version of the Blnk Ledger — ledgers, ledger balances, and transactions.
For ledgers
| Parameters | Sample usage | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| name | name:World | ||||||||
| ledger_id | ledger_id:=ldg_073f7ffe-9dfd-42ce-aa50-d1dca1788adc | ||||||||
| created_at | created_at:<2024-20-01 |
For balances
| Parameters | Sample usage | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| balance_id | balance_id:=bln_0be360ca-86fe-457d-be43-daa3f966d8f0 | ||||||||
| balance | balance:[100..100000] | ||||||||
| credit_balance | credit_balance:>100000 | ||||||||
| debit_balance | debit_balance:=2000000 | ||||||||
| currency | currency:[USD, GBP, EUR] | ||||||||
| precision | precision:=100 | ||||||||
| ledger_id | ledger_id:=ldg_073f7ffe-9dfd-42ce-aa50-d1dca1788adc | ||||||||
| created_at | created_at:<2024-20-01 |
For transactions
| Parameters | Sample usage | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| id | id:=txn_6164573b-6cc8-45a4-ad2e-7b4ba6a60f7d | ||||||||
| source | source:=bln_0be360ca-86fe-457d-be43-daa3f966d8f0 | ||||||||
| destination | destination:=bln_0be360ca-86fe-457d-be43-daa3f966d8f0 | ||||||||
| reference | reference:=ref_001adcfgf | ||||||||
| amount | amount:[2000..100000] | ||||||||
| currency | currency:[USD, GBP, EUR] | ||||||||
| status | status:[applied, queued] | ||||||||
| created_at | created_at:<2024-20-01 | ||||||||
| scheduled_for | scheduled_for:>2024-20-01 | ||||||||
| allow_over_draft | allow_over_draft:!=true | ||||||||
| inflight | inflight:=true |
4. Key considerations
Processing time
The time it takes to process a search query may vary depending on the kind and complexity of your search query.
For workflows where you need to display values in real-time like balances or a specific transaction details, used the GET by id endpoints specific to the collection you are searching for.
Data freshness
It is advisable not to use read-after-write flows (for example, searching immediately after a transaction request has been made) because the data may not be available immediately to search.
Under normal conditions, data is searchable within seconds, but propagation of new or updated data could be delayed due to unforeseen circumstances.
Need help?
We are very happy to help you make the most of Blnk, regardless of whether it is your first time or you are switching from another tool.
To ask questions or discuss issues, please join our Discord community.
Was this page helpful?