GraphQL query types

Edit online

The data that you import into your organization can be inspected by using GraphQL queries. You can run queries manually, automate your queries, or run queries through automated rules.

Querying Envizi Supply Chain Intelligence data uses GraphQL query instructions. The format of the query instruction includes the query type, input parameters enclosed in parentheses, followed by the output format for the returned object enclosed in curly brackets.

query type (input paramters){output parameters}

The query type indicates which type of data, either business events or business objects, is being queried and which data warehouse, either the event warehouse or the object warehouse, is being targeted. The input parameters indicate what is being queried, and the output format indicates how the resulting object must be displayed.

Currently, four main types of queries are possible, grouped by data warehouse:

Event Warehouse

errorEvents: Returns a list of error events based on error event details, which specifies the type of error to query: ingestion or processing. Returns an ErrorEventsCursor.

businessObjectEvents: Returns a list of business object events based on detail input from events that are affecting business objects. Returns a BusinessEventsCursor.

businessRuleEvents: Returns a list of business rule events based on detail input from events that result from the firing of a rule. Returns a BusinessRulesCursor.

Object Warehouse

businessObjects: Returns a list of business objects based on business object identification information and the name of a serialized view, which is used to perform the query. Returns a BusinessObjectsCursor.

The following sample query returns a single business object event by a specific ID:

{
  businessObjectEvents(
    simpleFilter: {
      businessObject: { 
        type: Order
        id: "372c9cdb-1077-464e-9132-b29fa25544d2"
      },
      tenantId: "e2_aRj_3np92C2Tl9uWIyh0vQP8N8"
    }, 
    cursorParams: { 
      first: 1  # Maximum number of items to return
    }
  ) {
    totalCount
    pageInfo {
      endCursor
      hasNextPage
    }
    edges {
      cursor
      object {
        eventCode
        infoHubObjectId
        objectType
        tenantId
        timestampEventOccurred
        timestampEventReceived
        eventDetails {
          ... on BusinessObjectEventDetails {
            businessObject {
              id
              type
            }
            eventSource {
              type
              EDI {
                transactionType
                size
              }
            }
          }
        }
      }
    }
  }
}

Query input parameters

The required input parameters differ based on the type of query that is performed. However, several input parameters are common across query types.

businessObjectEvents

The businessObjectEvents query type returns a list of business events from the event warehouse based on the input parameter values that are specified.

The input parameters for this query are:

eventParams: Points to a BusinessEventInput.

simpleFilter: Points to a BusinessObjectEventDetailsInput.

advancedFilter: Points to a BooleanExp.

savedFilter: Points to a SavedFilter.

cursorParams: Points to a CursorInput.

BusinessObjectEventDetailsInput

This type provides input on the business object operation that is involved in the event and contains the following attributes:

tenantId: The global ID of the tenant that is responsible for generating the event.

businessObjectEventCode: The type of business object operation that is involved in this event, either an upsert or archive.

businessObject: Points to a BusinessObjectInput.

BusinessObjectInput

This type provides input on the contained business object itself and contains the following attributes:

id: The globally unique ID of the business object, which is generated when the object was created.

type: Points to a BusinessObjectType enumeration value, which indicates the type of business object.

globalIdentifiers: A name or value pair array of object attributes that must uniquely identify this business object from other business objects of the same type and within the same tenant. Envizi Supply Chain Intelligence generates a unique ID for every unique combination of globalIdentifiers, tenant, and object type.

localIdentifiers: An ordered array of name or value pairs of object attributes that uniquely identify this object for local referencing within the business object itself. Certain business objects have nested objects that can refer back to the parent object, such as order lines and sublines within an order.

businessRuleEvents

The businessRuleEvents query type returns a list of business events from the event warehouse that is generated by a business rule based on the input parameter values that are specified.

Diagram of business rule event query types

The input parameters for this query are:

eventParams: Points to a BusinessEventInput.

simpleFilter: Points to a BusinessRuleEventDetailsInput.

advancedFilter: Points to a BooleanExp.

savedFilter: Points to a SavedFilter.

cursorParams: Points to a CursorInput.

aggregationParams: Points to an AggregationParams.

BusinessRuleEventDetailsInput

This type provides details on the business rule that generated the business event, and contains the following attributes:

tenantId: The global ID of the tenant that is responsible for generating the event.

rule: Points to a RuleInput type that allows you to specify the rule by ID, name, and source.

dimensionValues: An array of name/value pairs that specify the dimension values to restrict the query to. A dimension is an attribute of the underlying business object for which every unique value of that attribute generates a different business event.

AggregationParams

This type allows you to aggregate, summarize and sort the values that are returned in the query and contains the following attributes:

dimension: The underlying business object attribute and data type based on which aggregation occurs. For every unique value that is found for the specified attribute, a different aggregation is performed.

reduce: Optionally, a reduction operation can be performed on the data that is returned on the query, and it points to an AggregationReduce.

paginationParams: Allows you to optionally specify how many values to return in the query, which attribute to use to sort the results, and whether to sort them in ascending or descending order.

AggregationReduce

This type includes instructions on which type of reduction operation to perform and how the output of that reduction is expressed, and it includes the following attributes:

expression: Points to an AggregationReduceExpression.

output: Indicates the new attribute, resultAlias, to use to hold the result and data type of the expression output.

AggregationReduceExpression

This type holds the mathematical operation that defines the reduction algorithm, and it contains the following attributes:

operator: Points to an AggregationReduceOperator and specifies the mathematical operation that is performed.

fieldPath: The business object or event attribute that serves as input to the operation.

type: Points to a ScalarType and indicates the data type of the fieldPath value.

errorEvents

The errorEvents query type returns a list of error events from the event warehouse based on the input parameter values that are specified. Error events are generated by Envizi Supply Chain Intelligence when errors occur in the processing of business objects. Because data processing can happen asynchronously in the background, the only way to determine whether an error occurs is to query for error events.

The input parameters for this query are:

eventParams: Points to a BusinessEventInput.

simpleFilter: Points to a ErrorEventDetailsInput.

advancedFilter: Points to a BooleanExp.

savedFilter: Points to a SavedFilter.

cursorParams: Points to a CursorInput.

ErrorEventDetailsInput

This type provides details of the nature of the error event, and it includes the following attributes:

tenantId: The global ID of the tenant that is responsible for generating the event.

type: The type of error event, which signifies whether the event occurred during ingestion of data, IngestionErrorEventDetails, or background processing of the data, ProcessingErrorEventDetails.

businessObjects

The businessObjects query type returns a list of business objects from the object warehouse based on the input parameter values that are specified.

The input parameters for this query are:

hint: Points to a Hint type, which includes a viewId attribute that specifies a previously saved materialized view. Views define what is returned in the results of the query.

simpleFilter: Points to a BusinessObjectInput.

advancedFilter: Points to a BooleanExp.

savedFilter: Points to a SavedFilter.

cursorParams: Points to a CursorInput.

Common input parameter types

BooleanExp

Boolean expressions are series of comparisons that are linked with operators that result in a Boolean true or false result. The comparisons compare an explicit value with an attribute from an Envizi Supply Chain Intelligence business object or business event. Operations include the logical operators AND, OR, and NOT and comparison operators, such as GREATER_THAN and EQUALS. Logical operators are also of type BooleanExp, which enables recursion that allows BooleanExp statements to be arbitrarily nested.

Other referenced types include:

ComparisonOp: Compares a value of a specific type to an attribute of a business object or event that is indicated by the SELECT attribute.

ComparisonListOp: Compares a list of values of a specific type to an attribute of a business object or event that is indicated by the SELECT attribute. The business object or event attribute is assumed to also be a list, and so every item that is specified by VALUE must match every item that is returned by SELECT for the comparison to return true.

ComparisonOperandType: An enumeration of value data types that are used in comparisons.

Other common types

Diagram showing common input parameters type

BusinessEventInput: All types of business event queries support a common set of attributes about the event itself, such as timestamps for the event, the unique ID of the event, and the type of object that is involved in the event.

SavedFilter: Filters for refining the results of the query can be predefined by using the Filter Service and referenced by using the filterId attribute instead always expressing the filter details in the query.

CursorInput: Indicates after which business object or event the results must start by using the cursor value of that object or event for pagination purposes. Also indicates how many to return in the query.

AggregationReduceOperator: An enumeration of operations that are possible during a reduce operation while aggregating results in a business rule event query.

ScalarType: Refers to the data type of a value that is associated with an attribute during an aggregation operation.

SortOrder: Specifies how returned results must be sorted and the source field of the business object or event on which to sort.

BusinessObjectType: Lists all of the supported business object types in Envizi Supply Chain Intelligence.

Query output format

The data that is returned by the query depends on the type of query that is running. Likewise, the output format that is specified in the query itself also depends on the type of query. Because there are four query types, there are four possible returned objects and associated output formats.

errorEvents: ErrorEventsCursor
businessObjectEvents: BusinessEventsCursor
businessRuleEvents: BusinessRulesCursor
businessObjects: BusinessObjectsCursor

Each of the returned types implements the cursor interface, which means the results are an index-able, paginated list of objects.

Cursors

The Cursor interface has three base attributes:

edges: An array of object types that implement the Edge interface.

pageInfo: Details of the current page's data, including the cursor value, which is the pointer, of the last data object in the edges array, which is endCursor, and whether there is a next page, which is hasNextPage.

totalCount: The total number of data objects that match the query.

Three of the four query results cursors, ErrorEventsCursor, BusinessEventsCurs and BusinessObjectsCursor, closely resemble closely the Cursor interface definition and vary only on the object that is implemented in the Edge object. BusinessRulesCursor, however, differs by including more attributes in the Cursor implementation to handle rending aggregation results.

Note: Because of the wide variety of implementations of the object in the Edge type, according to the various types of business object and events that are implemented by Envizi Supply Chain Intelligence, the best way to learn more about their options is to introspect Envizi Supply Chain Intelligence data model as described in the GraphQL Introspection Tutorial

Edge

The Edge interface represents a cursored, or indexed, data object that matches the query criteria that are specified as input parameters to the query. The actual implementation depends on the type of data that is returned by the query. All implementations have the two attributes that are defined by the interface:

cursor: The unique index ID of the business object or event that is represented by this edge.

object: Points to a business object or event that implements the interface. The interface contains only the id attribute. Implementations vary widely depending on the type of data that is returned by the query.

BusinessRulesCursor

In addition to implementing the three attributes of the Cursor interface, which are edges, pageInfo, and totalCount, the BusinessRulesCursor also implements two more attributes for rendering aggregation results from the business rule:

aggregationResults: Points to an AggregationResult.

aggregationResultsTotalCount: The total number of returned aggregation results, according to matched dimensions.

AggregationResult

An aggregation defines a reduction calculation that is performed over multiple dimensions. A dimension is an attribute of the underlying business object for which every unique value of that attribute generates a different aggregation. There are two attributes in this type:

dimensionValues: An array of name and value pairs that list the dimension values for each aggregation value that was produced.

values: An array of name/value pairs where the name attribute specifies the resultAlias from the aggregation definition in the query and the value is the resulting computation (reduction). The value can either be a String (value) or float (numValue) type, depending on the nature of the reduction operation. The index of the value in the array corresponds to the index of its associated dimension in the dimensionValues array.