BSH Search

The BSH Search object is a powerful search system that allows you to search, filter, group, sort, and paginate data across entities in the BSH Engine. It provides a flexible and type-safe way to construct complex queries.

Documentation

Properties

`entity`

Specifies the target entity to search within.


{
    "entity": "users"
}

`fields`

Defines which fields to retrieve from the search results.


{
    "fields": ["id", "name", "email"]
}

`filters`

Use filters to build fetch data with conditions.


{
    "filters": [
        {
            "field": "age",
            "operator": "gte",
            "value": 18
        },
        {
            "operator": "or",
            "filters": [
                {
                    "field": "status",
                    "operator": "eq",
                    "value": "active"
                },
                {
                    "field": "salary",
                    "operator": "gt",
                    "value": 50000
                }
            ]
        }
    ]
}

Fields

Property	Description	Required
`operator`	The comparison or logical operator to use	yes
`field`	The field to apply the condition to	yes
`value`	The value to compare against	yes
`type`	Optional type specification for the field	no
`filters`	Nested filters to build complex conditions	if used logical operator

Comparison Operators

Operator	Description
`eq`	Equal to
`ne`	Not equal to
`gt`	Greater than
`gte`	Greater than or equal to
`lt`	Less than
`lte`	Less than or equal to
`like`	Pattern matching (case-sensitive)
`ilike`	Pattern matching (case-insensitive)
`contains`	Contains substring (case-sensitive)
`icontains`	Contains substring (case-insensitive)
`starts`	Starts with (case-sensitive)
`istarts`	Starts with (case-insensitive)
`in`	Value is in the provided array
`nin`	Value is not in the provided array
`between`	Value is between two values (inclusive)
`isnull`	Field is null
`notnull`	Field is not null

Logical Operators

Operator	Description
`and`	Logical AND operation
`or`	Logical OR operation

the logical operators are used to combine multiple queries using logical AND or OR operations.
By default, AND is used as the logical operator.

`groupBy`

Groups results by specified fields and applies aggregate functions.


{
    "groupBy": {
        "fields": ["department"],
        "aggregate": [
            {
                "function": "COUNT",
                "field": "id",
                "alias": "total_employees"
            },
            {
                "function": "AVG",
                "field": "salary",
                "alias": "avg_salary"
            }
        ]
    }
}

Fields

Property	Description	Required
`fields`	The fields to group by	no
`aggregate`	The aggregate functions to apply	no
`aggregate.function`	The aggregate function to apply	yes
`aggregate.field`	The field to aggregate	yes
`aggregate.alias`	The alias for the aggregated result	no

Function	Description
`COUNT`	Count the number of rows
`SUM`	Sum the values of the field
`AVG`	Find the average value of the field
`MIN`	Find the minimum value of the field
`MAX`	Find the maximum value of the field

`sort`

Defines the sorting order for the results.


{
    "sort": [
        {
            "field": "name",
            "direction": 1
        },
        {
            "field": "created_at",
            "direction": -1
        }
    ]
}

Property	Description	Required
`field`	The field to sort by	yes
`direction`	The direction to sort by (`1` for ascending, `-1` for descending)	yes

`pagination`

Controls the pagination of results.


{
    "pagination": {
        "page": 0,
        "size": 20
    }
}

Property	Description	Required	Default
`page`	The page number (0-based)	no	0
`size`	The number of items per page	no	10

TypeScript

TypeScript Definitions

Here are the complete TypeScript definitions for the BSH Search system:


type CaseInsensitive<T extends string> = T | Uppercase<T>;
 
export type BshSearch = {
    entity?: string
    fields?: string[]
    filters?: Filter[]
    groupBy?: GroupBy
    sort?: Sort[]
    pagination?: Pagination
}
 
export type LogicalOperator = "and" | "or";
export type ComparisonOperator =
    | "eq" | "ne"
    | "gt" | "gte"
    | "lt" | "lte"
    | "like" | "ilike"
    | "contains" | "icontains"
    | "starts" | "istarts"
    | "in" | "nin"
    | "between"
    | "isnull" | "notnull";
 
export type Filter = {
    operator?: ComparisonOperator | LogicalOperator;
    field?: string;
    value?: unknown;
    type?: string;
    filters?: Filter[];
};
 
export type GroupBy = {
    fields?: string[]
    aggregate?: Aggregate[]
}
 
export type AggregateFunction =
    | "COUNT"
    | "SUM"
    | "AVG"
    | "MIN"
    | "MAX"
 
export type Aggregate = {
    function?: AggregateFunction
    field?: string
    alias?: string
}
 
export type Sort = {
    field?: string
    direction?: -1 | 1
}
 
export type Pagination = {
    page?: number
    size?: number
}

Examples

Simple Example


{
    "entity": "users",
    "fields": ["id", "name", "email"],
    "filters": [
        {
            "field": "email",
            "operator": "contains",
            "value": "@bsh.com"
        }
    ],
    "pagination": {
        "page": 0,
        "size": 10
    }
}

This filters will search for users with email containing @bsh.com and return the first 10 results.

Complete Example

Here’s a comprehensive example that demonstrates all the features:


{
    "entity": "employees",
    "fields": ["id", "name", "email", "salary", "department"],
    "filters": [
        {
            "field": "age",
            "operator": "gte",
            "value": 25
        },
        {
        "operator": "and",
        "filters": [
            {
                "field": "status",
                "operator": "eq",
                "value": "active"
            },
            {
                "operator": "or",
                "filters": [
                    {
                        "field": "department",
                        "operator": "in",
                        "value": ["engineering", "marketing"]
                    },
                    {
                        "field": "salary",
                        "operator": "gt",
                        "value": 50000
                    }
                ]
            }
        ]
        }
    ],
    "groupBy": {
        "fields": ["department"],
        "aggregate": [
            {
                "function": "COUNT",
                "alias": "employee_count"
            },
            {
                "function": "AVG",
                "field": "salary",
                "alias": "avg_salary"
            }
        ]
    },
    "sort": [
        {
            "field": "department",
            "direction": 1
        },
        {
            "field": "avg_salary",
            "direction": -1
        }
    ],
    "pagination": {
        "page": 0,
        "size": 10
    }
}

This filters will:

Search the employees entity
Filter for employees aged 25 or older who are active
Further filter for those in engineering/marketing departments OR with salary > 50000
Group results by department
Count employees and calculate average salary per department
Sort by department name (ascending) then by average salary (descending)
Return the first 10 results

Best Practices

Specify fields to reduce data transfer and improve performance
Use appropriate operators - prefer ilike over like for user-facing searches
Structure queries logically - use proper nesting for complex conditions
Apply pagination for large result sets to improve performance
Use aggregation for summary data rather than processing large datasets client-side

BSH Search

Documentation

Properties

entity

fields

filters

Fields

Comparison Operators

Logical Operators

groupBy

Fields

Aggregate Functions

sort

pagination

TypeScript

TypeScript Definitions

Examples

Simple Example

Complete Example

Best Practices

Best Practices

`entity`

`fields`

`filters`

`groupBy`

`sort`

`pagination`