> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blnkfinance.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Querying Parameters
> Learn how to use the query field.
export const CtaCallout = props => {
const {title, buttonLabel, href, trackingEvent, buttonTarget, rel = "noopener noreferrer", children} = props;
const handleCtaClick = () => {
if (typeof window === "undefined" || !trackingEvent) {
return;
}
try {
window.dispatchEvent(new CustomEvent("blnk:docs-cta", {
detail: {
name: trackingEvent,
href
}
}));
} catch {}
try {
window.posthog?.capture?.(trackingEvent, {
href
});
} catch {}
const gaPayload = {
cta_href: href
};
try {
window.gtag?.("event", trackingEvent, gaPayload);
} catch {}
try {
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
event: trackingEvent,
...gaPayload
});
} catch {}
};
const isExternal = typeof href === "string" && (/^https?:\/\//i).test(href);
const target = buttonTarget ?? (isExternal ? "_blank" : undefined);
const linkRel = isExternal ? rel : undefined;
return ;
};
The querying parameters `q` and `query_by` work together to control what data you search for and which fields to search in. These parameters enable you to perform full-text searches, exact matches, and wildcard queries across your ledger data.
The `q` parameter is required in all search requests. The `query_by` parameter is required when searching for specific terms, and optional only when using the wildcard `*`.
***
## Quick start
Here's a basic search query that demonstrates both parameters:
```bash cURL wrap theme={"system"}
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/transactions" \
-H "X-Blnk-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"q": "bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e",
"query_by": "source,destination"
}'
```
```typescript TypeScript wrap theme={"system"}
const response = await blnk.Search.search(
{ q: 'bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e', query_by: 'source,destination' },
'transactions',
);
```
```go Go wrap theme={"system"}
results, resp, err := client.Search.SearchDocument(
blnkgo.SearchParams{
Q: "bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e",
QueryBy: "source,destination",
},
blnkgo.Transactions,
)
```
```json Response expandable theme={"system"}
{
"found": 3,
"hits": [
{
"document": {
"amount": 5000,
"amount_string": "5000",
"atomic": false,
"created_at": 1720363463,
"currency": "USD",
"description": "Payment for services",
"destination": "bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e",
"effective_date": 1720363463,
"source": "bln_86ba7976-499d-4282-955e-a7c2abf5db12",
"status": "APPLIED",
"transaction_id": "txn_4c86b65e-8249-4b3b-8000-b907d32f9a9f"
},
"highlights": [
{
"field": "destination",
"matched_tokens": ["bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e"],
"snippet": "bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e"
}
]
}
]
}
```
***
## Query parameters
### Exact text search
Search for specific text or IDs by specifying the fields to search in:
```bash cURL wrap theme={"system"}
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/transactions" \
-H "X-Blnk-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"q": "bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e",
"query_by": "source,destination"
}'
```
```typescript TypeScript wrap theme={"system"}
const response = await blnk.Search.search(
{
q: "bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e",
query_by: "source,destination",
},
'transactions',
);
```
```go Go wrap theme={"system"}
results, resp, err := client.Search.SearchDocument(
blnkgo.SearchParams{Q: "bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e", QueryBy: "source,destination"},
blnkgo.Transactions,
)
```
### Wildcard search
Use `*` to return all records (only case where `query_by` is optional):
```bash cURL wrap theme={"system"}
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/balances" \
-H "X-Blnk-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"q": "*"
}'
```
```typescript TypeScript wrap theme={"system"}
const response = await blnk.Search.search(
{
q: "*",
},
'balances',
);
```
```go Go wrap theme={"system"}
results, resp, err := client.Search.SearchDocument(
blnkgo.SearchParams{Q: "*"},
blnkgo.Balances,
)
```
### Multi-word search
Search for multiple words across specified fields:
```bash cURL wrap theme={"system"}
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/transactions" \
-H "X-Blnk-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"q": "payment services",
"query_by": "description"
}'
```
```typescript TypeScript wrap theme={"system"}
const response = await blnk.Search.search(
{
q: "payment services",
query_by: "description",
},
'transactions',
);
```
```go Go wrap theme={"system"}
results, resp, err := client.Search.SearchDocument(
blnkgo.SearchParams{Q: "payment services", QueryBy: "description"},
blnkgo.Transactions,
)
```
Multi-word searches require ALL words to be present in the document. For "payment services", both "payment" AND "services" must exist in the specified fields.
### Single vs multiple fields
Search in one field or across multiple fields using comma separation:
```bash theme={"system"}
# Single field
{
"q": "john",
"query_by": "first_name"
}
# Multiple fields
{
"q": "john doe",
"query_by": "first_name,last_name,email"
}
```
### Metadata search
Available in version 0.11.0 and later.
Search within metadata or nested objects using dot notation:
```bash cURL wrap theme={"system"}
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/transactions" \
-H "X-Blnk-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"q": "transfer",
"query_by": "meta_data.transaction_type,description"
}'
```
```typescript TypeScript wrap theme={"system"}
const response = await blnk.Search.search(
{
q: "transfer",
query_by: "meta_data.transaction_type,description",
},
'transactions',
);
```
```go Go wrap theme={"system"}
results, resp, err := client.Search.SearchDocument(
blnkgo.SearchParams{Q: "transfer", QueryBy: "meta_data.transaction_type,description"},
blnkgo.Transactions,
)
```
***
## Common patterns
This finds all transactions where the specified balance ID appears as either source or destination.
```bash cURL wrap theme={"system"}
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/transactions" \
-H "X-Blnk-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"q": "bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e",
"query_by": "source,destination"
}'
```
```typescript TypeScript wrap theme={"system"}
const response = await blnk.Search.search(
{
q: "bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e",
query_by: "source,destination",
},
'transactions',
);
```
```go Go wrap theme={"system"}
results, resp, err := client.Search.SearchDocument(
blnkgo.SearchParams{Q: "bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e", QueryBy: "source,destination"},
blnkgo.Transactions,
)
```
This searches for "alice" across name and email fields, useful for customer support.
```bash cURL wrap theme={"system"}
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/identities" \
-H "X-Blnk-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"q": "alice",
"query_by": "first_name,last_name,email"
}'
```
```typescript TypeScript wrap theme={"system"}
const response = await blnk.Search.search(
{
q: "alice",
query_by: "first_name,last_name,email",
},
'identities',
);
```
```go Go wrap theme={"system"}
results, resp, err := client.Search.SearchDocument(
blnkgo.SearchParams{Q: "alice", QueryBy: "first_name,last_name,email"},
blnkgo.Identities,
)
```
This finds transactions containing "refund" in their description or reference fields.
```bash cURL wrap theme={"system"}
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/transactions" \
-H "X-Blnk-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"q": "refund",
"query_by": "description,reference"
}'
```
```typescript TypeScript wrap theme={"system"}
const response = await blnk.Search.search(
{
q: "refund",
query_by: "description,reference",
},
'transactions',
);
```
```go Go wrap theme={"system"}
results, resp, err := client.Search.SearchDocument(
blnkgo.SearchParams{Q: "refund", QueryBy: "description,reference"},
blnkgo.Transactions,
)
```
***
## Best practices
* **Be specific with fields**: Target relevant fields in `query_by` for better performance.
* **Validate field names**: Invalid fields in `query_by` may return unexpected results.
***
## 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 [contact us](mailto:support@blnkfinance.com) or [join our Discord community](https://discord.gg/7WNv94zPpx).
Sign up and manage your ledger with our back-office dashboard. You can invite teammates to collaborate and manage your ledger operations directly from the dashboard.