The Vitruvi Functions from the previous section can be used in a number of ways to reference the RAW and _Query API endpoints. The following M-code examples are provided for reference.

_Query API Endpoints

When querying the query API endpoints, the function used is the same as for the RAW API endpoints and so if much of the same method to call it. The primary difference is in the method for _filtering the data.

The _query endpoints use a parameter called $filter to specify the filter criteria as described in _Query API Filtering. Please use the API documentation for a list of all the filter syntax that is available.

Example 1 - Simple _Query query

let 
    // Simplest example - just call the endpoint for a given _query endpoint and view the results.
    // In this example, the filter, field list and display name lists are just set to null.
    // This should only be used when exploring the data. To limit the load on the server, 
    // field selections and/or filtering should be used.
    Source = fVitruviPagedQuery("/api/v1/wbs/work_items_query/", 5000, null, null, null)
in
    Source

Example 2 - Select Fields

let 

    // This example builds on the previous example by selecting a subset of fields to be returned. 
    // This helps keep your data models small and improve query performance.
    
    // Start by creating an M list containing the names of all the fields you want to query
    FieldNames = {"id","display_name","work_order_name","work_package_name"},
    
    // Now pass the field list into the Vitruvi function
    Source = fVitruviPagedQuery("/api/v1/wbs/work_items_query/", 5000, null, FieldNames, null)

in
    Source

Example 3 - Display Names

let 

    // The fields in Vitruvi are "snake case" - that is all lower case and underscores for spaces. Sometimes it is 
    // cleaner for the query to return cleaner display names. This can be done by also supplying a list of display 
    // names that corresponds to the field names list.

    // Start by creating an M list containing the names of all the fields you want to query
    FieldNames = {"id","display_name","work_order_name","work_package_name"},

    // Then create an M list containing the display names for the corresponding fields you want to query
    DisplayNames = {"Work Item Id", "Work Item Name", "Work Order Name", "Work Package Name"},

    // Now pass both the field and display name lists into the Vitruvi function
    Source = fVitruviPagedQuery("/api/v1/wbs/work_items_query/", 5000, null, FieldNames, DisplayNames)
in
    Source

Example 4 - Simple Filtering

let 

    // Returning ALL records in a given model is often unnecessary and, again, leads to large data models 
    // and poor performance. In this example, we will apply a simple filter to only get the work items where 
    // the work order name is "Drop".

    FieldNames = {"id","display_name","work_order_name","work_package_name"},
    DisplayNames = {"Work Item Id", "Work Item Name", "Work Order Name", "Work Package Name"},

    // Create a record with a field name equal to the filter criteria.
    // In this case, we are applying a simple "equals" criteria to the field work_order_name.
    // For a full list of all the filter criteria, please see the Filtering _Query APIs wiki page.
    QueryFilter = [#"$filter"="work_order_name eq 'Drops'"],

    // Now pass the filter into the Vitruvi function along with both the field and display name lists
    Source = fVitruviPagedQuery("/api/v1/wbs/work_items_query/", 5000, QueryFilter, FieldNames, DisplayNames)
in
    Source

Example 5 - Advanced Filtering

let 

    // This example will demonstrate how to apply compaound criteria to the filter. For more information on how
    // filters work on the _Query endpoints, please see the Filtering _Query APIs wiki page.

    FieldNames = {"id","display_name","work_order_name","work_package_name"},
    DisplayNames = {"Work Item Id", "Work Item Name", "Work Order Name", "Work Package Name"},

    // The filter for _Query APIs allow for compound statements in a single string. In this case, lets assume that 
    // we only want records where the work_order_name is "Drops" and the work_item_name only contains "aerial drop" 
    // or "buried drop". In this case, the filter would be:
    QueryFilter = [#"$filter"="work_order_name eq 'Drops' and (contains(tolower(display_name), 'aerial drop') or contains(tolower(display_name), 'buried drop'))"],

    // Now pass the filter into the Vitruvi function along with both the field and display name lists
    Source = fVitruviPagedQuery("/api/v1/wbs/work_items_query/", 5000, QueryFilter, FieldNames, DisplayNames)
in
    Source