Class DataQuery

java.lang.Object
com.morpheusdata.core.data.DataQuery
Direct Known Subclasses:
DatasetQuery

public class DataQuery extends Object
This is the query object to use to query data from a MorpheusDataService. This allows the developer to use complex queries when looking up MorpheusModel objects. It is often recommended a UserIdentity or AccountIdentity object be assigned to the DataQuery so that the query appropriately restricts access to objects relevant to the specific user or account.

Additionally, complex filters can be applied using a new filter list syntax.

Example Filters Syntax (Groovy representation):


 dataQuery.withFilters(
   new DataOrFilter(
   	new DataFilter("name","=","David"),
   	new DataAndFilter(
   		new DataFilter<String>("name","!=","Fred"),
   		new DataFilter<String>("name","!=","Al")
   	)
   )
 )
 

As can be seen in the example, the filters is a Collection of DataFilters containing a property name (i.e. name), a property value (i.e. value), and an operator. An operator can either be a "==","=","!=","<","<=",">",">=","=~","in","or,"and".

Since:
0.15.1
See Also:
  • Field Details

    • user

      public UserIdentity user
      Specifies the User object scope for the query. This is implemented by User objects.
    • account

      public AccountIdentity account
      Specifies the Account object scope for the query. This is implemented by Account objects.

      Note: If a user is specified on the query, this property is ignored unless the user is from the master account.

    • phrase

      public String phrase
      Allows for a search phrase to be used to arbitrarily search a set of MorpheusModel objects. This phrase, by default, searches a set of properties specific to the particular model.

      Additionally a dynamic query syntax DSL is provided that allows for more complex search criteria to be entered in a free form manner.

      The following example will query the object for a name exactly equal to 'Fred' and a type exactly equal to 'Apache')

           name=Fred AND type='Person'
       

      Most operators are available as defined in the filters when using dynamic queries. An operator can either be a "==","=","!=","<","<=",">",">=","=~","or,"and".

      A common example may be to match an object with a name of Fred Smith but just by searching for fred.

           name:Fred AND type='Person'
       
      In essense the query DSL is a list of (PROPERTY + OPERATOR + VALUE) mixed and matched with OR and AND operations.
    • parameters

      public ApiParameterMap<String,Object> parameters
      This is an HTTP Request parameter override. If this is used in a UIExtensionProvider, and the request params are passed here, they will be parsed into the DataQuery as an override for a more direct map. An example might be ?max=25&offset=25. There are also more complex parameters available that can be passed into the Query to be documented below
      • phrase The search string
      • max The maximum number of results to return
      • offset The current offset of results to fetch
      • sort The property to sort by.
      • order The order of the sort by. (i.e. asc or desc)
      • range A range query can query a set of objects based on a date range and is dynamic. It contains sub properties for endDate,startDate,type, and count

        Example range query for finding objects from the last for weeks might be:

        
             	?range.endDate=now&range.type=weeks&range.count=4
             

      Note: This property is mostly UI specific and not often used in reports or sync related use cases.

    • filters

      public Collection<DataFilter> filters
    • joins

      public Collection<String> joins
      A list of joins for marshalling during path traversal and during query (i.e. 'interfaces.network') on a ComputeServer would ensure network is marshalled regardless of max depth of traversal
    • propertyList

      public Collection<String> propertyList
      A list of property names to load instead of the full object.

    • max

      public Long max
      Sets a max results count if needed for paging. In the case of a sync service, all results would be ideal.
    • offset

      public Long offset
      Sets a query offset for paging. Use this in combination with the max property.
    • sort

      public String sort
      The property by which to sort by (i.e. name)
    • order

      public DataQuery.SortOrder order
      The default sort order to send the data back based on the sort property name. (i.e. Ascending (ASC) or , Descending (DESC)).
  • Constructor Details

    • DataQuery

      public DataQuery()
    • DataQuery

      public DataQuery(UserIdentity user)
      Creates an initial DataQuery scoped to a User. This is useful for scoping some queries based on user tenant access.

      Note: A user scoped query is not guaranteed to restrict based on resource permissions for the user. This is up to the DataService implementation.

      Parameters:
      user - the User to scope the query to
    • DataQuery

      public DataQuery(AccountIdentity account)
      Creates an initial DataQuery scoped to an Account. This is useful for scoping some queries based on tenant.

      Note: A tenant scoped query is not guaranteed to restrict based on resource permissions for the tenant. This is up to the DataService implementation.

      Parameters:
      account - the Account to scope the query to
    • DataQuery

      public DataQuery(UserIdentity user, Map<String,Object> parameters)
    • DataQuery

      public DataQuery(AccountIdentity account, Map<String,Object> parameters)
  • Method Details

    • withFilter

      public DataQuery withFilter(DataFilter dataFilter)
      A chainable filter method for applying an "==" operator filter given a property name and desired value to lookup.
      Parameters:
      dataFilter - the filter object to apply to the list of query filters
      Returns:
      the current DataQuery object for chaining
    • withFilter

      public DataQuery withFilter(String name, Object value)
      A chainable filter method for applying an "==" operator filter given a property name and desired value to lookup.
      Parameters:
      name - the property name for the filter to query against.
      value - the value to compare the property to
      Returns:
      the current DataQuery object for chaining
    • withFilter

      public DataQuery withFilter(String name, String operator, Object value)
      A chainable filter method for applying an "==" operator filter given a property name and desired value to lookup.
      Parameters:
      name - the property name for the filter to query against.
      operator - the operator to be used for comparing the value (i.e. ==,!=,<,<=,>>=,in,=~,:)
      value - the value to compare the property to.
      Returns:
      the current DataQuery object for chaining
    • withFilters

      public DataQuery withFilters(Map<String,Object> filter)
    • withParameters

      public DataQuery withParameters(Map<String,Object> parameters)
    • withFilters

      public DataQuery withFilters(Collection<DataFilter> filters)
      Appends a set of filters to the existing filters list. This operation is additive and does not clear the current filters list. For information on the available filter types please refer to the top of this classes description.
      Parameters:
      filters - a Collection of Filter objects for building custom queries.
      Returns:
      the current DataQuery object for chaining
      See Also:
    • withFilters

      public DataQuery withFilters(DataFilter... filters)
      Appends a set of filters to the existing filters list. This operation is additive and does not clear the current filters list. For information on the available filter types please refer to the top of this classes description.
      Parameters:
      filters - a Collection of Filter objects for building custom queries.
      Returns:
      the current DataQuery object for chaining
      See Also:
    • withJoin

      public DataQuery withJoin(String join)
      Appends a join key for data query optimization as well as marshalling from the database. These keys can use periods between property names in models to traverse more deeply
      Parameters:
      join - the join string (i.e. 'interfaces.network')
      Returns:
      the current DataQuery object for chaining
    • withJoins

      public DataQuery withJoins(Collection<String> joins)
      Appends join keys for data query optimization as well as marshalling from the database. These keys can use periods between property names in models to traverse more deeply
      Parameters:
      joins - a collection join strings (i.e. 'interfaces.network')
      Returns:
      the current DataQuery object for chaining
    • withJoins

      public DataQuery withJoins(String... joins)
      Appends join keys for data query optimization as well as marshalling from the database. These keys can use periods between property names in models to traverse more deeply
      Parameters:
      joins - a collection join strings (i.e. 'interfaces.network')
      Returns:
      the current DataQuery object for chaining
    • withSort

      public DataQuery withSort(String sort)
      Sets the sort of the DataQuery
      Parameters:
      sort - property to sort by
      Returns:
      the current DataQuery object for chaining
    • withSort

      public DataQuery withSort(String sort, DataQuery.SortOrder order)
      Sets the sort of the DataQuery
      Parameters:
      sort - property to sort by
      order - direction of the sort
      Returns:
      the current DataQuery object for chaining
    • putAt

      public Object putAt(String key, Object value)
    • put

      public Object put(String key, Object value)
    • putAll

      public void putAll(Map<String,Object> parameters)
    • getAt

      public Object getAt(String key)
    • get

      public Object get(String key)
    • list

      public Collection<Object> list(String key)
    • findParameter

      public String findParameter(String key)
    • getPageConfig

      public Map<String,Object> getPageConfig()
      Generates a Map of page configuration data to be sent into the Morpheus DataViewService (internal). This method is typically not used directly and is reserved for internal use.
      Returns:
      a Map of properties used for setting page metadata on the query
    • toMap

      public Map<String,Object> toMap()
      Converts the DataQuery to a Map
      Returns:
      a Map of properties based on the values assigned in this object.