QueryOptions & CustomField

`QueryOptions` is a container class that bundles all common OData parameters into a single, easy-to-use object. It works seamlessly with the `F` object to handle `$filter` expressions and provides intelligent helpers for `$custom` and `$expand`.

Importing Helpers

To use these features, import the necessary helpers from the `easy_acumatica.models` module.


from easy_acumatica.models.filter_builder import F  
from easy_acumatica.models.query_builder import QueryOptions, CustomField

Building Queries

Basic Usage

Combine a filter with other parameters like `$select`, `$top`, and `$skip` for pagination.


# Create a filter using the F object
my_filter = (F.Category == 'Hardware') & (F.Stock < 20)

# Bundle it into QueryOptions for a paginated request
opts = QueryOptions(
    filter=my_filter,
    select=["ItemID", "Name", "Stock"],
    top=50,
    skip=100 # Requesting the third page of 50 items
)

# .to_params() generates the final dictionary for the request
params = opts.to_params()

Smart Custom Fields (`$custom`)

The `custom` parameter accepts a list of `CustomField` objects, which makes formatting safe and easy. A key feature is that if you request a custom field from a detail entity (e.g., "Details"), `QueryOptions` will automatically add that entity to the `$expand` list for you, preventing common errors.


opts = QueryOptions(
    filter=F.Type == 'SalesOrder',
    expand=["MainContact"], # Note: "Details" is NOT included here
    custom=[
        # A custom field on the top-level entity
        CustomField.field("OrderProperties", "UsrPriority"),

        # A custom field on the "Details" entity
        CustomField.field("Transactions", "UsrSpecialCode", entity_name="Details"),
        
        # A user-defined attribute
        CustomField.attribute("Document", "OPERATSYST")
    ]
)

params = opts.to_params()
# params['$expand'] will be 'Details,MainContact'
# "Details" was added automatically!

Using Raw String Filters

If you need to use complex OData syntax not covered by the `F` object, you can always provide a raw string to the `filter` parameter as an escape hatch.


opts = QueryOptions(
    filter="substringof('special', Description) and Price gt 100",
    select=["Description", "Price"]
)