queryMapped() — Entity Service

General Description

The queryMapped operation retrieves related entities for a specific entity based on a reference property.

Detailed Description

This operation is specifically designed for querying related entities through a reference property. It's particularly useful for retrieving entities in many-to-many or one-to-many relationships. Unlike the standard query operation, queryMapped requires an entityId (the parent entity) and a mapColName (the reference property name) to determine which related entities to retrieve.

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

Same as the standard query operation, with these additional/required parameters:

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.
entityId	string	Yes	Property for entity ID of the parent entity whose related entities you want to retrieve.
mapColName	string	Yes	Name of the reference property that defines the relationship.
propertyName	string	No	Alternative to mapColName, also specifies the reference property name.
refColName	string	No	Getter/setter for mapColName.
selectCols	array	No	Array of SelectCol objects defining columns to select in the query. If not provided, all columns are selected.
filters	array	No	Array of Filter objects to filter the related entities.
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.
includes	array	No	Array of IncludeQuery objects for additional related entities to include in the results.
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).

Response

Success Response

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

Error Response

{
    "success": false,
    "error": "Error message describing what went wrong"
}

Example Usage

Basic Mapped Query

// Get all order items for a specific order
const result = await queryMapped({
  queryParams: {
    entDefName: "Order",
    entityId: "order-123",
    mapColName: "items"
  }
});

if (result.success) {
  const orderItems = result.entities;
  console.log(`Order has ${orderItems.length} items`);
  orderItems.forEach(item => {
    console.log(`- ${item.quantity} x ${item.productName} (${item.unitPrice})`);
  });
} else {
  console.error("Error:", result.error);
}

Filtered Mapped Query

// Get active users in a specific group
const result = await queryMapped({
  queryParams: {
    entityDef: {
      name: "Group"
    },
    entityId: "group-456",
    mapColName: "members",
    filters: [
      {
        col: { name: "status" },
        val: { value: "active" },
        function: 0 // QueryFunction.Equals (default)
      }
    ],
    sortCols: [
      {
        col: { name: "lastName" },
        sortType: "asc"
      }
    ]
  }
});

if (result.success) {
  const activeMembers = result.entities;
  console.log(`Group has ${activeMembers.length} active members`);
}

Mapped Query with Nested Includes

// Get products in a category with their suppliers
const result = await queryMapped({
  queryParams: {
    entDefName: "Category",
    entityId: "category-789",
    mapColName: "products",
    includes: [
      {
        propertyName: "supplier",
        includes: [
          {
            propertyName: "address",
            count: 1, // take only one address
            filters: [
              {
                col: { name: "isDefault" },
                val: { value: true },
                function: 0 // QueryFunction.Equals
              }
            ]
          }
        ]
      }
    ]
  }
});

if (result.success) {
  const products = result.entities;
  products.forEach(product => {
    if (product.supplier) {
      console.log(`${product.name} supplied by ${product.supplier.name}`);
      if (product.supplier.address) {
        console.log(`  Supplier address: ${product.supplier.address.city}, ${product.supplier.address.country}`);
      }
    }
  });
}

Mapped Query with Aggregation

// Get count of orders by status for a specific customer
const result = await queryMapped({
  queryParams: {
    entDefName: "Customer",
    entityId: "customer-123",
    mapColName: "orders",
    selectCols: [
      {
        name: "status",
        groupBy: true
      },
      {
        name: "id",
        aggregateFunction: 3, // AggregateFunction.Count
        selectAsTitle: "orderCount"
      }
    ]
  }
});

if (result.success) {
  const orderStats = result.entities;
  orderStats.forEach(stat => {
    console.log(`${stat.status}: ${stat.orderCount} orders`);
  });
}

Additional Information

• The queryMapped operation is specifically designed for retrieving related entities through a reference property.
• It requires both the parent entity ID (entityId) and the reference property name (mapColName).
• The operation follows the reference defined in the entity definition to retrieve the related entities.
• This operation is particularly useful for:
  • Retrieving items in a many-to-one relationship (e.g., order items for an order)
  • Retrieving entities in a many-to-many relationship (e.g., users in a group)
  • Retrieving any related entities where the reference property is defined as multiple
• The operation supports all the filtering, sorting, pagination, and analytical capabilities of the standard query operation.
• For standard entity queries without relationship mapping, use the query operation instead.
• Access permissions are enforced based on the provided token.
• Does not work with reference properties that are defined as single.
• All SelectCol, Filter, SortCol, and IncludeQuery objects follow the same structure as the standard query operation.
• Use QueryFunction enum values (0-27) for filter functions.
• Use AggregateFunction enum values (0-6) for analytical queries.
• Use DateModifier enum values (0-11) for time-based grouping.
• Alternatively, you can use query operation on reference entity definition with filter, or query operation on same entity definition with include.
  • Example:
    • entity: Order
    • reference property: items
    • query on OrderItem with filter order_id = 'order-123'
    • query on Order with include items and filter id = 'order-123'
    • queryMapped on Order with mapColName = 'items' and entityId = 'order-123'