4.1 The query builder🔗

Use make-query to construct a query. All arguments are optional—use only what you need:

(make-query

#:filter filter-expr    ; which records to return

#:select field-list     ; which fields to include

#:expand field-list     ; which related records to include

#:orderby field-or-pair ; how to sort results

#:top n                 ; maximum records to return

#:skip n)               ; records to skip (for pagination)

Pass the query to an entity function using the #:query keyword:

(customers #:query (make-query #:top 5))

4.2 Filtering records🔗

The #:filter argument takes a filter expression built from bcnav’s filter functions.

4.3 Selecting fields🔗

By default, BC returns all fields for each record. Use #:select to request only the fields you need:

(customers #:query (make-query

#:select '(id displayName email phoneNumber)))

This reduces response size and can improve performance, especially when records have many fields.

Some fields are always included regardless of #:select, particularly the record’s ID and ETag.

4.4 Expanding related records🔗

Many BC entities have relationships to other entities. For example, a sales order has lines, a customer has a default currency, etc. Normally, you’d need separate API calls to fetch related data. With #:expand, you get everything in one request:

;; Get sales orders with their line items

(sales-orders #:query (make-query

#:expand '(salesOrderLines)))

;; Get customers with their currency and payment terms

(customers #:query (make-query

#:expand '(currency paymentTerm)))

The expanded records appear as nested data in the response. For example, with #:expand '(salesOrderLines), each order hash will have a 'salesOrderLines key containing a list of line item hashes.

To discover what can be expanded, use inspect (covered in Metadata Discovery).

4.5 Sorting results🔗

Use #:orderby to control the sort order. You can specify just a field name (ascending) or a pair of field and direction:

;; Sort by displayName ascending (default)

(customers #:query (make-query #:orderby 'displayName))

;; Sort by amount descending

(sales-orders #:query (make-query #:orderby '(amount . desc)))

;; Sort ascending explicitly

(items #:query (make-query #:orderby '(number . asc)))

BC’s OData implementation doesn’t support sorting by multiple fields in a single request.

4.6 Limiting and paginating results🔗

Use #:top to limit how many records are returned:

;; Get just the first 10 customers

(customers #:query (make-query #:top 10))

Use #:skip with #:top for manual pagination:

;; Page 1: records 1-10

(customers #:query (make-query #:top 10 #:skip 0))

;; Page 2: records 11-20

(customers #:query (make-query #:top 10 #:skip 10))

However, bcnav handles pagination automatically by default. When you call (customers), bcnav follows BC’s @odata.nextLink to fetch all pages. You can disable this if needed:

;; Disable auto-pagination globally

(current-bc-auto-paginate #f)

;; Or for just one call using parameterize

(parameterize ([current-bc-auto-paginate #f])

(customers))  ;; Returns only the first page

4.7 Composing queries🔗

The query-with-* functions let you modify an existing query, creating a new one without changing the original:

> (define base-query (make-query #:select '(id displayName)))

> base-query

(query #f '(id displayName) #f #f #f #f)

> (query-with-filter base-query (eq 'status "Open"))

(query status eq 'Open' '(id displayName) #f #f #f #f)

; Original is unchanged:

> base-query

(query #f '(id displayName) #f #f #f #f)

This is useful for building up queries incrementally or creating variations:

(define customer-base

(make-query #:select '(id displayName email)))

(define active-customers

(query-with-filter customer-base (eq 'blocked #f)))

(define ca-customers

(query-with-filter active-customers (eq 'state "CA")))

4.8 Seeing the generated query string🔗

For debugging, you can see what OData parameters bcnav will send:

> (query->params     (make-query       #:filter (and: (eq 'status "Open") (gt 'amount 1000))       #:select '(id displayName amount)       #:top 50))

'(($filter . "(status eq 'Open' and amount gt 1000)")   ($select . "id,displayName,amount")   ($top . "50"))

This returns an association list that bcnav converts to URL query parameters.

4.9 Common patterns🔗

Here are some queries you might find useful:

4.10 Next steps🔗

Now that you understand querying, continue to Working with Entities to learn about creating, updating, and deleting records.