Skip to content

querying.md

Latest commit

 

History

History
145 lines (98 loc) · 2.8 KB

querying.md

File metadata and controls

145 lines (98 loc) · 2.8 KB

Querying Data

Basic GET

# Get all records (first page)
bcli get customers

# Limit results
bcli get customers --top 10

# Get a single record by ID
bcli get customers "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

OData Filtering

Business Central APIs use OData v4 query syntax.

Filter

# Equality
bcli get customers --filter "displayName eq 'Fabrikam'"

# Comparison
bcli get salesInvoices --filter "totalAmountIncludingTax gt 1000"

# Contains
bcli get items --filter "contains(displayName, 'Chair')"

# Date filtering
bcli get generalLedgerEntries --filter "postingDate ge 2024-01-01"

# Combined (AND)
bcli get salesInvoices --filter "status eq 'Open' and totalAmountIncludingTax gt 500"

Select Fields

bcli get customers --select displayName,email,phoneNumber
bcli get items --select number,displayName,unitPrice,inventory

Expand Navigation Properties

bcli get salesOrders --expand salesOrderLines
bcli get customers --expand defaultDimensions

Sort

bcli get customers --orderby "displayName asc"
bcli get salesInvoices --orderby "totalAmountIncludingTax desc"

Pagination

# Skip and take
bcli get customers --skip 20 --top 10

# Get ALL records (follows @odata.nextLink automatically)
bcli get customers --all

# Include total count
bcli get customers --count --top 5

Output Formats

Control output with the global --format (-f) flag:

# Rich table (default)
bcli get customers --top 5

# JSON (for scripting, piping to jq)
bcli -f json get customers --top 5

# CSV (for spreadsheets, Excel)
bcli -f csv get customers --top 5 > customers.csv

# NDJSON (newline-delimited JSON, for streaming pipelines)
bcli -f ndjson get customers --all

# Raw (includes @odata metadata fields)
bcli -f raw get customers --top 1

Pipe to jq

bcli -f json -q get customers --top 100 | jq '.[] | select(.city == "Chicago") | .displayName'

Export to CSV

bcli -f csv -q get items --select number,displayName,unitPrice --all > items.csv

Context Banner

By default, bcli shows the active profile, environment, and company before output:

[profile: production | env: Production | company: CRONUS USA]

Suppress it with --quiet (-q):

bcli -q get customers --top 5

Verbose Mode

See resolved URLs and timing:

bcli -v get customers --top 5
# Endpoint: customers (v2.0 (standard))
# OData: {'$top': '5'}

Dry Run

Preview what would execute without making any requests:

bcli --dry-run get customers --filter "city eq 'Chicago'" --top 10
# --dry-run: would execute GET, skipping.

Ad-Hoc Custom API Queries

If an endpoint isn't in your registry, use explicit route flags:

bcli get myCustomEntity --publisher mycompany --group api --version v1.0 --top 5