@gsb-core/mcp-docs/src/docs/query.ts

Documentation for GSB MCP implementations

/**
 * Documentation for the query operation
 */

/**
 * Returns documentation for the query operation
 * @return {string} markdown documentation
 */
export function queryDocs(): string {
  return `
# Query Operation

## General Description

The \`query\` operation fetches entities based on specified query parameters, allowing for complex filtering, sorting, pagination, and analytical queries.

## Detailed Description

This operation provides a powerful and flexible way to search and retrieve entities based on various criteria. It supports filtering by property values, sorting results, paginating through large result sets, and including related entities. The query system is designed to handle complex queries while maintaining performance. Additionally, it supports analytical queries with groupBy, aggregates, and modifiers for data analysis.

## Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| queryParams | object | Yes | The query parameters object that defines the search criteria and result options. |
| token | string | No | Authentication token for your request. If not provided, the system will use the default API key from environment variables. |
| tenantCode | string | No | Tenant code to specify which tenant's data to access. If not provided, the system will extract it from the token or use the default tenant code from environment variables. |

### QueryParams Object Structure

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| entDefName | string | Yes* | Name of the entity definition to query. Required if entDefId is not provided. Getter/setter for entityDef.name. |
| entDefId | string | Yes* | ID of the entity definition to query. Required if entDefName is not provided. Getter/setter for entityDef.id. |
| entityDef | object | No | Entity definition object with id and/or name properties. |
| entity | object | No | Optional entity instance for the query. |
| id | string | No | ID of this query. |
| entityId | string | No | Property for entity ID. |
| selectCols | array | No | Array of SelectCol objects defining columns to select in the query. If not provided, all columns are selected. |
| includes | array | No | Array of IncludeQuery objects for related entities to include in the results. |
| filters | array | No | Array of Filter objects to filter the results. |
| startIndex | number | No | Pagination start index (0-based). |
| count | number | No | Number of records to return. |
| sortCols | array | No | Array of SortCol objects for sorting specifications. |
| calcTotalCount | boolean | No | Whether to calculate the total count of matching records. |
| searchText | string | No | Search term for automatic searching across all searchable fields. |
| queryType | number | No | Type of query using QueryType enum (Single=0, List=1, Search=2, AutoComplete=3, Full=4, FullWithSingleRefs=5, FullNonPersonal=6). |
| disableTransaction | boolean | No | Whether to disable database transaction for this query. |
| propertyName | string | No | Name of the property being queried when using relationship queries. |
| propName | string | No | Alias for propertyName. |
| mapColName | string | No | Alias for propertyName used in mapping. |
| refColName | string | No | Getter/setter for mapColName. |

### SelectCol Object Structure

| Property | Type | Description |
|----------|------|-------------|
| name | string | Name of the column/property to select. |
| aggregateFunction | number | Aggregate function using AggregateFunction enum (None=0, Sum=1, Average=2, Count=3, Maximum=4, Minimum=5, Variance=6). |
| dateModifier | number | Date modifier using DateModifier enum (None=0, Year=1, Quarter=2, Month=3, DayOfYear=4, DayOfMonth=5, Week=6, Weekday=7, Hour=8, Minute=9, Second=10, Millisecond=11). |
| script | string | JavaScript expression to calculate the column value. |
| groupBy | boolean | Whether this column is used for grouping in analytical queries. |
| fullName | string | Full name of the column including table prefixes. |
| title | string | Display title for UI purposes. |
| value | any | Static value for the column. |
| nameScript | string | Script to generate the column name dynamically. |
| valScript | string | Script to generate the column value dynamically. |
| selectAsTitle | string | Alias name for the selected column in results. |

### SortCol Object Structure

| Property | Type | Description |
|----------|------|-------------|
| col | SelectCol | The column to sort by. |
| sortType | string | Sort direction: "asc" for ascending, "desc" for descending. |

### Filter Object Structure

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| col | SelectCol | Yes | The column to filter on. |
| val | SelectCol | Yes | The value to compare against as a SelectCol object. |
| function | number | No | The comparison function using QueryFunction enum. |
| relation | string | No | The logical relation to other filters ("and", "or"). |
| children | array | No | Nested filter conditions for complex queries. |
| negate | boolean | No | Whether to negate the condition (default: false). |
| name | string | No | Optional name for the filter. |
| relationLevel | number | No | Level of relation nesting. |

### IncludeQuery Object Structure

IncludeQuery extends QueryParams and represents related entities to include:

| Property | Type | Description |
|----------|------|-------------|
| name | string | Name of the relationship property to include. |
| propertyName | string | Alias for name. |
| (all QueryParams properties) | various | All properties from QueryParams are available for nested queries. |

## Response

### Success Response

\`\`\`json
{
    "success": true,
    "entities": [
        // Array of matching entities
        {
            "id": "string",
            "property1": "value1",
            "property2": "value2",
            // ...
        }
    ],
    "totalCount": 42,  // Present only if calcTotalCount is true
    "message": "string",  // Optional message
    "status": 200  // Optional status code
}
\`\`\`

## Query Functions (QueryFunction Enum)

The query system supports various functions for filtering entities:

| Function | Enum Value | Description | Example |
|----------|------------|-------------|---------|
| Equals | 0 | Exact value match | \`{ col: { name: "status" }, val: { value: "active" }, function: 0 }\` |
| Like | 1 | Pattern matching | \`{ col: { name: "name" }, val: { value: "John%" }, function: 1 }\` |
| Greater | 2 | Greater than comparison | \`{ col: { name: "price" }, val: { value: 100 }, function: 2 }\` |
| Smaller | 3 | Smaller than comparison | \`{ col: { name: "quantity" }, val: { value: 50 }, function: 3 }\` |
| NotEqual | 4 | Not equal comparison | \`{ col: { name: "status" }, val: { value: "inactive" }, function: 4 }\` |
| BitwiseAnd | 5 | Bitwise AND operation | \`{ col: { name: "flags" }, val: { value: 8 }, function: 5 }\` |
| BitwiseOr | 6 | Bitwise OR operation | \`{ col: { name: "flags" }, val: { value: 4 }, function: 6 }\` |
| BitwiseXor | 7 | Bitwise XOR operation | \`{ col: { name: "flags" }, val: { value: 2 }, function: 7 }\` |
| In | 8 | Check if value is in a set | \`{ col: { name: "status" }, val: { value: ["active", "pending"] }, function: 8 }\` |
| Is | 9 | Type checking (null/not null) | \`{ col: { name: "createDate" }, val: { value: null }, function: 9 }\` |
| IsNot | 10 | Type checking negation | \`{ col: { name: "createDate" }, val: { value: null }, function: 10 }\` |
| FullTextSearch | 11 | Full text search | \`{ col: { name: "description" }, val: { value: "search terms" }, function: 11 }\` |
| Contains | 12 | Containment check for multiple related entities | \`{ col: { name: "tags" }, val: { value: ["id-of-the-related-entity"] }, function: 12 }\` |
| GreaterOrEqual | 13 | Greater than or equal comparison | \`{ col: { name: "price" }, val: { value: 100 }, function: 13 }\` |
| SmallerOrEqual | 14 | Smaller than or equal comparison | \`{ col: { name: "quantity" }, val: { value: 50 }, function: 14 }\` |
| ILike | 15 | Case-insensitive pattern matching | \`{ col: { name: "name" }, val: { value: "john%" }, function: 15 }\` |
| RegexMatch | 16 | Regular expression matching | \`{ col: { name: "email" }, val: { value: ".*@domain\\.com" }, function: 16 }\` |
| RegexMatchCaseInsensitive | 17 | Case-insensitive regex matching | \`{ col: { name: "email" }, val: { value: ".*@DOMAIN\\.COM" }, function: 17 }\` |
| IsNull | 18 | Check if value is null | \`{ col: { name: "deletedAt" }, val: { value: null }, function: 18 }\` |
| Between | 19 | Check if value is between two values | \`{ col: { name: "price" }, val: { value: [100, 500] }, function: 19 }\` |
| PhraseSearch | 20 | Phrase-based text search | \`{ col: { name: "content" }, val: { value: "exact phrase" }, function: 20 }\` |
| GeometryOverlaps | 21 | Geometry overlap check | \`{ col: { name: "area" }, val: { value: geometryObject }, function: 21 }\` |
| PointInGeometry | 22 | Point within geometry check | \`{ col: { name: "location" }, val: { value: pointObject }, function: 22 }\` |
| GPSDistance | 23 | GPS distance calculation | \`{ col: { name: "coordinates" }, val: { value: [lat, lng, distance] }, function: 23 }\` |
| GPSWithinRadius | 24 | GPS within radius check | \`{ col: { name: "coordinates" }, val: { value: [lat, lng, radius] }, function: 24 }\` |
| JsonContains | 25 | JSON containment check | \`{ col: { name: "metadata" }, val: { value: {"key": "value"} }, function: 25 }\` |
| JsonHasKey | 26 | JSON key existence check | \`{ col: { name: "metadata" }, val: { value: "keyName" }, function: 26 }\` |
| MatchArrays | 27 | Array matching | \`{ col: { name: "tags" }, val: { value: ["tag1", "tag2"] }, function: 27 }\` |

## Aggregate Functions (AggregateFunction Enum)

The query system supports the following aggregate functions for analytical queries:

| Function | Enum Value | Description | Example |
|----------|------------|-------------|---------|
| None | 0 | No aggregation | \`{ name: "id", aggregateFunction: 0 }\` |
| Sum | 1 | Sum of values | \`{ name: "amount", aggregateFunction: 1, selectAsTitle: "total_amount" }\` |
| Average | 2 | Average of values | \`{ name: "price", aggregateFunction: 2, selectAsTitle: "average_price" }\` |
| Count | 3 | Count of records | \`{ name: "id", aggregateFunction: 3, selectAsTitle: "total_records" }\` |
| Maximum | 4 | Maximum value | \`{ name: "price", aggregateFunction: 4, selectAsTitle: "highest_price" }\` |
| Minimum | 5 | Minimum value | \`{ name: "price", aggregateFunction: 5, selectAsTitle: "lowest_price" }\` |
| Variance | 6 | Variance of values | \`{ name: "score", aggregateFunction: 6, selectAsTitle: "score_variance" }\` |

## Date Modifiers (DateModifier Enum)

For time-based grouping and analysis:

| Modifier | Enum Value | Description |
|----------|------------|-------------|
| None | 0 | No date modification |
| Year | 1 | Group by year |
| Quarter | 2 | Group by quarter |
| Month | 3 | Group by month |
| DayOfYear | 4 | Group by day of year |
| DayOfMonth | 5 | Group by day of month |
| Week | 6 | Group by week |
| Weekday | 7 | Group by weekday |
| Hour | 8 | Group by hour |
| Minute | 9 | Group by minute |
| Second | 10 | Group by second |
| Millisecond | 11 | Group by millisecond |

## Query Types (QueryType Enum)

| Type | Enum Value | Description |
|------|------------|-------------|
| Single | 0 | Single entity query |
| List | 1 | List of entities |
| Search | 2 | Search query |
| AutoComplete | 3 | Autocomplete query |
| Full | 4 | Full entity data |
| FullWithSingleRefs | 5 | Full data with single references |
| FullNonPersonal | 6 | Full  data excluding createDate,lastUpdateDate,createdBy,lastUpdatedBy|

## Example Usage

### Basic Query

\`\`\`typescript
const result = await query({
  queryParams: {
    entDefName: "Customer",
    filters: [
      {
        col: { name: "status" },
        val: { value: "active" },
        function: 0 // QueryFunction.Equals
      }
    ]
  }
});

if (result.success) {
  const customers = result.entities;
  console.log(\`Found \${customers.length} active customers\`);
}
\`\`\`

### Query with Pagination and Sorting

\`\`\`typescript
const result = await query({
  queryParams: {
    entDefName: "Order",
    startIndex: 0,
    count: 10,
    sortCols: [
      {
        col: {
          name: "orderDate"
        },
        sortType: "desc"
      }
    ],
    calcTotalCount: true
  }
});

if (result.success) {
  const orders = result.entities;
  const totalOrders = result.totalCount;
  console.log(\`Showing \${orders.length} of \${totalOrders} total orders\`);
}
\`\`\`

### Complex Query with Multiple Conditions

\`\`\`typescript
const result = await query({
  queryParams: {
    entDefName: "Product",
    filters: [
      {
        relation: "or",
        children: [
          {
            col: { name: "price" },
            val: { value: 500 },
            function: 2 // QueryFunction.Greater
          },
          {
            col: { name: "inStock" },
            val: { value: true },
            function: 0 // QueryFunction.Equals
          }
        ]
      }
    ],
    sortCols: [
      {
        col: { name: "price" },
        sortType: "asc"
      }
    ]
  }
});
\`\`\`

### Using SelectCol with Scripts

\`\`\`typescript
const result = await query({
  queryParams: {
    entDefName: "Order",
    selectCols: [
      {
        name: "totalPrice",
        selectAsTitle: "total",
        nameScript: "([totalPrice]+[shipping])*[vatRate] - [discount]"
      }
    ],
    filters: [
      {
        col: { name: "orderDate" },
        val: { value: "2023-01-01" },
        function: 2 // QueryFunction.Greater
      }
    ]
  }
});

if (result.success) {
  console.log(\`Found \${result.entities.length} orders\`);
}
\`\`\`

### Using Simple Search

\`\`\`typescript
const result = await query({
  queryParams: {
    entDefName: "Product",
    searchText: "smartphone", // Will search across all searchable fields
    startIndex: 0,
    count: 20
  }
});

if (result.success) {
  const products = result.entities;
  console.log(\`Found \${products.length} products matching 'smartphone'\`);
}
\`\`\`

### Including Related Entities

\`\`\`typescript
const result = await query({
  queryParams: {
    entDefName: "Order",
    includes: [
      {
        propertyName: "customer"
      },
      {
        propertyName: "items",
        includes: [
          {
            propertyName: "product"
          }
        ]
      }
    ]
  }
});
\`\`\`

## Additional Information

- For complex queries, the filter conditions can be nested using the children property.
- The relation property in filter conditions can be "and" or "or" to specify how conditions are combined.
- The relation set in the parent query will be used for all child queries, if not specified, the default relation is "and".
- If any child query has a relation, it will override the parent query relation.
- The negate property can be set to true to invert a condition (NOT).
- When using includes, you can nest includes to fetch deeply related entities using IncludeQuery objects.
- For better performance with large result sets, use pagination with startIndex and count.
- The calcTotalCount option adds overhead to the query, so only use it when needed.
- For direct access to a single entity by ID, use the getById operation instead.
- The searchText parameter provides a simple way to search across all searchable fields.
- For more complex search requirements, use explicit filter conditions.
- The response contains entities directly in the \`entities\` field, not in a \`data\` field.

### SelectCol Usage

- The SelectCol object provides extensive configuration options for column selection.
- Use aggregateFunction with AggregateFunction enum values for analytical queries.
- Use dateModifier with DateModifier enum values for time-based grouping.
- The selectAsTitle property allows you to alias column names in results.
- Scripts (nameScript, valScript) can contain JavaScript expressions for dynamic calculations.
- The groupBy property is essential for analytical queries with aggregations.

### Filter Usage

- The Filter object uses SelectCol for both col and val properties.
- The val.value property contains the actual comparison value.
- Use QueryFunction enum values for the function property.
- The relation property uses QueryRelation enum values ("and", "or").
- Nested filters using children array allow complex logical conditions.

### Full text search
  - to be able to use full text search, the property should be marked as fullTextIndex=true
  - you can use FullTextSearch function (QueryFunction.FullTextSearch = 11) in filters to search for a string in the property, or simply set searchText in the main query.
  - example queryParams:
       \`\`\`typescript
        const queryParams = {
        entDefName: "HelpPage",
        searchText: "data t",
  //if any help page has a title like "data table" or the en_us column of its associated content has "data table" will be selected.
  selectCols: [
  {
    //will apply logical search on title property: title like '%data t%'
    "name": "title"
  },
  {
    //will apply full text search on related content.en_us property (it's already marked as fullTextIndex=true)
    "selectAsTitle": "highlight", // alias name for the result column
    "searchHighlight": "data t", // search text to be highlighted, if not provided will return all content instead of highlight. 
    "name": "content.en_us" // property name to be searched, we can use dot notation to search in nested properties.
  }
]
}
\`\`\`

response, data is highlighted with html tags. en_us column name is set to highlight because we set the selectAsTitle to highlight.

\`\`\`json
{
    "entities": [
        {
            "title": "Data Table",
            "content": {
                "highlight": "<b>Data</b> Table  \n\n The <b>data</b> table may display varying features across different sections or devices. It is designed"
            }
        }
    ]
}
 \`\`\`

### Analytical Queries

- Use groupBy property in SelectCol objects to aggregate data by specific fields.
- Aggregates define calculations to perform on grouped data using AggregateFunction enum:
  - Count (3): Count the number of records in each group
  - Sum (1): Calculate the total of a numeric field
  - Average (2): Calculate the average of a numeric field
  - Minimum (5): Find the minimum value
  - Maximum (4): Find the maximum value
  - Variance (6): Calculate variance of values
- The selectAsTitle property in SelectCol defines the field name in the result.
- If it's an analytical query, set groupBy or aggregateFunction to all selectCols, filters, includes and sorts. 
- groupBy flag in a filter is automatically transformed as having by the system.
- Analytical queries return aggregated data instead of complete entities.
- For time-series analysis you can use dateModifier with DateModifier enum values.
- Please refer to documentation for advanced usage. You can use sub queries, calculated fields, scripts, etc.

example, get users who have a role with id 699b313c-cf1c-40c1-b86e-ab6e9a53f4f2, and group by their group and createDate based on addedYear.
*note: all columns in the selectCols and sorts are either group by or aggregate function.
\`\`\`typescript
{
  "entityDef": {
    "name": "GsbUser"
  },
  "filters": [
    {
      "children": [
        {
          "col": {
            "name": "roles"
          },
          "val": {
            "value": [
              {
                "id": "699b313c-cf1c-40c1-b86e-ab6e9a53f4f2"
              }
            ]
          },
          "function": 12 // QueryFunction.Contains for many-to-many relation
        }
      ]
    }
  ],
  "selectCols": [
    //group by groups, system automatically understands it's a many-to-many relation and does all the work.
    {
      "name": "groups",
      "groupBy": true
    },
    //count the number of groups, we can use title or any field just to count
    {
      "name": "title",
      "aggregateFunction": 3, // AggregateFunction.Count
      "selectAsTitle": "count"
    },
    //group by createDate based on addedYear
    {
      "name": "createDate",
      "dateModifier": 1, // DateModifier.Year
      "groupBy": true,
      "selectAsTitle": "addedYear"
    }
  ],
  "sortCols": [
    //sort by createDate based on addedYear
    {
      "col": {
        "name": "createDate",
        "groupBy": true,
        "dateModifier": 1 // DateModifier.Year
      },
      "sortType": "desc"
    }
  ]
}
\`\`\`
`;
}

/**
 * Returns a brief summary of the query operation.
 * @return {string} A short description of the function.
 */
export function querySummary(): string {
  return `
**Purpose**: Searches and retrieves entities based on complex criteria.

**When to use**:
- Filtering entities by property values
- Sorting and paginating results
- Including related entities
- Performing analytical operations

**Inputs**:
- queryParams: Object with entity definition, filters, sorting, pagination {entDefName/entDefId: string, selectCols: [...,{name: string, aggregateFunction?: number, groupBy?: boolean}], filters: [...,{col: {name: string}, val: {value: any}, function?: number}], sortCols?: [...,{col: {name: string}, sortType?: string}], startIndex?: number, count?: number, calcTotalCount?: boolean, searchText?: any, queryType?: number}
- token (optional)
- tenantCode (optional)

**Returns**: Matching entities and optional total count.
`;
}

export default queryDocs;