Search

Several system methods are provided to search and filter results by their metadata. For example, /system/findDataObjects can return a list of all data objects that you can access, filtered by name, tags, types, regions, properties, etc.

Regular Expressions and Globbing

In some of these routes, you can restrict your search to names matching a particular regular expression or a glob (wildcard pattern). For the glob pattern, we support the wildcard * for matching a string of any length, and the wildcard ? for matching a single character. (We do not at this moment support the bracket notation [].) If you are searching for the actual characters "*", "?", or "\", you will need to escape them with a backslash, e.g. "\*a\?xfoo\\" matches the exact string "*a?xfoo\".

Pagination of Results

The limit and starting input parameters, together with the next output field, can be used to paginate the results. The limit parameter determines the maximum number of returned results. If there are more results than limit allowed for, then next is non-null and may be used as the starting argument for a subsequent call. If the call is repeated with the starting input parameter set to the previous call's next return value, then the next unique subset of results will be returned. Repeat this process until next is null to retrieve all results.

List of Search API Methods

Search API Method Specifications

API method: /system/findDataObjects

Specification

Searches for data objects satisfying particular constraints. By default this will return all entities and objects for which the user has at least "VIEW" permission (permission acquired by PUBLIC nature of a project is not counted in this criterion). This constraint cannot be removed. However, additional constraints can be specified that can further restrict the objects that will be returned.

Ordering of results

Data objects from the same project always appear together in the search results in descending order of their last modified timestamp, with ties broken in ascending order of their IDs.

Inputs

  • class string (optional) The entity type to restrict the search by. Must be one of "record", "file", "applet", "workflow".
  • state string (optional, default "any") One of the values: "open", "closing", "closed", or "any"
  • visibility string (optional, default "visible") One of the values: "hidden", "visible", or "either"
  • name string or mapping (optional) If a string, the exact case-sensitive name that the results must have. If a mapping, then it can have a subset of the following fields:
    • regexp string (mutually exclusive with glob; required if glob is not present) A PCRE regular expression that the name of all results must match
    • flags string (optional; can only be present if regexp is present) Currently this field can only have value "i", which denotes that case-insensitive matching should be performed with the regular expression
    • glob string (mutually exclusive with regexp; required if regexp is not present) A wildcard pattern that the name of all results must match. The valid wildcard characters are '*' (0 or more characters) and '?' (1 character).
  • id array of strings (optional) If provided, results must have object IDs among the provided list of IDs. The array may have no more than 1000 elements. (Note that the number of results may exceed the number of IDs provided here because an object appears once in the results for each accessible project it is found in, unless scope.project is set.)
  • type string or mapping (optional) Defined by grammar below, represents the type(s) that any results must have
    • type ::= < string >
    • type ::= {"$and": typeArray}
    • type ::= {"$or": typeArray}
    • typeArray ::= [ ]
    • typeArray ::= [type, ...]
  • tags string or mapping (optional) Defined by grammar below, represents the tag(s) any results must have
    • tags ::= < string >
    • tags ::= {"$and": tagsArray}
    • tags ::= {"$or": tagsArray}
    • tagsArray ::= [ ]
    • tagsArray ::= [tags, ...]
  • region string or array of strings (optional) If a string, then the result set will contain only entities whose associated region matches the string. If an array, then the result set will contain only entities whose associated region is one of the specified strings.
  • properties mapping (optional) Defined by grammar below. If provided, each matching result must have the specified properties. Each "key" is a property name, and each "value" may either be a string (meaning that the key must have the specified value) or the boolean true (meaning that the specified key must be present but may have any value).
    • constraint ::= { key: value, ... }
    • constraint ::= { "$and": constraintArray }
    • constraint ::= { "$or": constraintArray }
    • constraintArray ::= []
    • constraintArray ::= [constraint, ...]
  • link string (optional) An object ID to which matching objects must link to in their details
  • scope mapping (optional) Restrict the search to a particular project
    • project string ID of the project in which all results must reside
    • folder string (optional, default "/") Folder path in project in which all results must reside
    • recurse boolean (optional, default true) Whether the search should be performed recursively on subfolders as well
  • level string (optional, default "VIEW") One of: "VIEW", "UPLOAD", "CONTRIBUTE", or "ADMINISTER", representing the minimum permissions level by which to restrict the list of projects searched
  • modified mapping (optional) If at least one of the following keys is specified, the resulting data objects must have been last modified in the indicated time frame. If not specified, there will be no constraint on when the data object was last modified. If a modified hash does not contain at least one of the following keys, an error will be thrown.
    • after timestamp (optional) If specified, only return results that were last modified at or after this time
    • before timestamp (optional) If specified, only return results that were last modified at or before this time
  • created mapping (optional) If at least one of the following keys is specified, the resulting data objects must have been created in the indicated time frame. If not specified, there will be no constraint on data object creation time. If a created hash does not contain at least one of the following keys, an error will be thrown.
    • after timestamp (optional) If specified, only return results created at or after this time
    • before timestamp (optional) If specified, only return results created at or before this time
  • describe boolean or mapping (optional, default false) Either false to indicate that no extra metadata should be retrieved with the results, or a mapping representing the input that would be used for calling "describe" on each of the returned results
  • starting mapping (optional) Continue a previous query that had reached its limit; the non-null value that was returned as next in the query's output should be provided here.
  • limit int (optional, default 1000) Maximum number of results that may be returned; must be between 1 and 1000 (inclusive)

Outputs

  • results array of mappings List of results, each with the following fields:

    • project string ID of the project in which the result was found
    • id string ID of the result

    If describe was set to a mapping:

    • describe mapping The output of the result's corresponding describe method
  • next mapping or null If null, all results were reported in results. If a mapping, represents the next result that could not be returned because limit results have already been returned. This value should be passed directly to starting in a subsequent query if more results are desired.

Errors

  • InvalidInput

    • The input is not a hash
    • class (if supplied) is not one of: "record", "file", "applet", or "workflow"
    • state (if supplied) is not one of: "open", "closing", "closed", or "any"
    • visibility (if supplied) is not one of: "hidden", "visible", or "either"
    • level (if supplied) is not one of: "VIEW", "UPLOAD", "CONTRIBUTE", or "ADMINISTER"
    • name (if supplied) is not a string or a mapping such that any of the following is satisfied
      • flags is present, but key regexp is missing or the value supplied to flags is not "i".
      • Mutually exclusive keys glob and regexp are provided together
      • Neither glob nor regexp is present
    • id (if supplied) is an array containing greater than 1000 elements
    • type, properties, or tags (if supplied) do not take any of the specified grammars
    • region (if supplied) is not one of our supported regions. See (https://wiki.dnanexus.com/API-Specification-v1.0.0/Regions) for more information
    • modified or created (if supplied) does not contain either an after or before timestamp
    • limit is not between 1 and 1000
  • PermissionDenied

    • VIEW access to the project specified in scope.project is required if scope.project is supplied

API method: /system/findExecutions

Specification

Searches for execution (job or analysis) objects.

Ordering of results

Jobs and analyses returned by /system/findExecutions, /system/findJobs, and /system/findAnalyses are sorted by their created timestamp (in descending order, i.e., the latest execution appears first). Ties are broken in ascending order of their IDs.

Inputs

  • class string (optional) Entity type to restrict the search by; must be either "job" or "analysis"
  • includeSubjobs boolean (optional, default true) If set to false, only non-subjob executions (i.e., master jobs, origin jobs, or analyses) will be returned
  • launchedBy string (optional) ID of the user who launched the job
  • name string or mapping (optional) If a string, the exact case-sensitive name that the results must have. If a mapping, then it can have a subset of the following fields:
    • regexp string (mutually exclusive with glob; required if glob is not present) A PCRE regular expression that the name of all results must match
    • flags string (optional; can only be present if regexp is present) Currently this field can only have value "i", which denotes that case-insensitive matching should be performed with the regular expression
    • glob string (mutually exclusive with regexp; required if regexp is not present) A wildcard pattern that the name of all results must match. The valid wildcard characters are '*' (0 or more characters) and '?' (1 character).
  • id array of strings (optional) If provided, results must have execution IDs among the provided list of IDs. The array may have no more than 1000 elements.
  • executable string (optional) ID of the executable (app or applet) that the results were responsible for running
  • project string (optional) ID of the project context, or the project in which the job was launched
  • tags string or mapping (optional) Defined by grammar below, represents the tag(s) any results must have
    • tags ::= < string >
    • tags ::= {"$and": tagsArray}
    • tags ::= {"$or": tagsArray}
    • tagsArray ::= [ ]
    • tagsArray ::= [tags, ...]
  • properties mapping (optional) Defined by grammar below. If provided, each matching result must have the specified properties. Each "key" is a property name, and each "value" may either be a string (meaning that the key must have the specified value) or the boolean true (meaning that the specified key must be present but may have any value).
    • constraint ::= { key: value, ... }
    • constraint ::= { "$and": constraintArray }
    • constraint ::= { "$or": constraintArray }
    • constraintArray ::= []
    • constraintArray ::= [constraint, ...]
  • state string or array of strings (optional) State(s) that the results must be in. Possible values by execution type:

    Execution type States
    Job idle, waiting_on_input, runnable, running, waiting_on_output, done, debug_hold, failed, terminating, terminated
    Analysis in_progress, done, partially_failed, failed, terminating, terminated

    Queries to /system/findExecutions can use states from either list.

  • rootExecution string or array of strings (optional) One or more IDs of the top-level (user-initiated) execution(s); results will be constrained to executions in those execution trees

  • originJob string or array of strings (optional) Restrict results to executions which have one of the provided string IDs as an origin job; an origin job is one launched via /app-xxxx/run or /applet-xxxx/run, or as a stage in an analysis

  • parentJob string or null (optional) If the value is a string, then all results must be executions directly launched by parentJob. If the value is null, then only executions with no parent job are searched. Use null values for this field and parentAnalysis in order to restrict the search to root executions only.

  • parentAnalysis string or null (optional) If the value is a string, then all results must be executions launched as stages of parentAnalysis. If the value is null, then only executions which do not have a parent analysis are searched. Use null values for this field and parentJob in order to restrict the search to root executions only.

  • created mapping (optional) If at least one of the following keys is specified, the resulting execution objects must have been created in the indicated time frame. If not specified, there will be no constraint on execution object creation time. If a created hash does not contain at least one of the following keys, an error will be thrown.

    • after timestamp (optional) If specified, only return results created at or after this time
    • before timestamp (optional) If specified, only return results created at or before this time
  • describe boolean or mapping (optional, default false) False indicates that no extra metadata should be retrieved with the results. A mapping represents the input that would be used for calling the corresponding "describe" API method on each of the returned results; a value of true is equivalent to the empty hash input.

  • starting string (optional) Continue a previous query that had reached its limit; the non-null value that was returned as next in the query's output should be provided here

  • limit int (optional, default 1000) Maximum number of results that may be returned; must be between 1 and 1000 (inclusive)

Outputs

  • results array of mappings List of results, each with the following fields:

    • id string ID of the result

    If describe was set to true or a mapping:

    • describe mapping The output of the result's corresponding describe method
  • next string or null If null, all results were reported in results. If a string, represents the next result that could not be returned because limit results have already been returned. This value should be passed directly to starting in a subsequent query if more results are desired.

Errors

See Errors (Protocols)

API method: /system/findAnalyses

This method is identical to /system/findExecutions with the class constraint set to "analysis".

API method: /system/findJobs

This method is identical to /system/findExecutions with the class constraint set to "job".

API method: /system/findApps

Specification

This route provides functionality to search for apps; the ordering of results is arbitrary. Only apps for which the requesting user has access to will be returned (for example, the user is on the authorized users list for the app).

Inputs

  • name string or mapping (optional) If a string, the exact case-sensitive name that the results must have. If a mapping, then it can have a subset of the following fields:
    • regexp string (mutually exclusive with glob; required if glob is not present) A PCRE regular expression that the name of all results must match
    • flags string (optional; can only be present if regexp is present) Currently this field can only have value "i", which denotes that case-insensitive matching should be performed with the regular expression
    • glob string (mutually exclusive with regexp; required if regexp is not present) A wildcard pattern that the name of all results must match. The valid wildcard characters are '*' (0 or more characters) and '?' (1 character).
  • category string (optional) A category an app must be tagged with
  • allVersions boolean (optional, default false) Whether to remove the restriction that only app versions tagged with "default" are returned
  • published boolean (optional) If true, only published apps are returned; if false, only unpublished apps are returned
  • billTo string or array of strings (optional) If a string, then the result set will contain only apps whose billTo matches the string. If an array, then the result set will contain only apps whose billTo is one of the specified entities.
  • createdBy string (optional) ID of the user who created the app
  • developer string (optional) ID of a developer the app must have
  • authorizedUser string (optional) userID, orgID or "PUBLIC" that must exist in each app's authorizedUsers list
  • modified mapping (optional) If at least one of the following keys is specified, the resulting apps must have been last modified in the indicated time frame. If not specified, there will be no constraint on when the app was last modified. If a modified hash does not contain at least one of the following keys, an error will be thrown.
    • after timestamp (optional) If specified, only return results that were last modified at or after this time
    • before timestamp (optional) If specified, only return results that were last modified at or before this time
  • created mapping (optional) If at least one of the following keys is specified, the resulting apps must have been created in the indicated time frame. If not specified, there will be no constraint on app creation time. If a created hash does not contain at least one of the following keys, an error will be thrown.
    • after timestamp (optional) If specified, only return results created at or after this time
    • before timestamp (optional) If specified, only return results created at or before this time
  • describe boolean or mapping (optional, default false) False indicates that no extra metadata should be retrieved with the results. A mapping represents the input that would be used for calling /app-xxxx/describe on each of the returned results; a value of true is equivalent to the empty hash input.
  • starting string (optional) Continue a previous query that had reached its limit; the value that was returned as next in the query's output should be provided here
  • limit int (optional, default 1000) Maximum number of results that may be returned; must be between 1 and 1000 (inclusive)

Outputs

  • results array of mappings List of results, each with the following fields:

    • id string ID of the result

    If describe was set to true or a mapping:

    • describe mapping The output of the result's corresponding describe method
  • next string or null If null, all results were reported in results. If a string, represents the next result that could not be returned because limit results have already been returned. This value should be passed directly to starting in a subsequent query if more results are desired.

Errors

See Errors (Protocols)

API method: /system/findProjects

Specification

Find projects accessible to a user or job at a given permission level.

Ordering of results is:

  • Descending by last modified time stamp, then
  • Ascending by ID

Inputs

  • name string or mapping (optional) If a string, the exact case-sensitive name that the results must have. If a mapping, then it can have a subset of the following fields:
    • regexp string (mutually exclusive with glob; required if glob is not present) A PCRE regular expression that the name of all results must match
    • flags string (optional; can only be present if regexp is present) Currently this field can only have value "i", which denotes that case-insensitive matching should be performed with the regular expression
    • glob string (mutually exclusive with regexp; required if regexp is not present) A wildcard pattern that the name of all results must match. The valid wildcard characters are '*' (0 or more characters) and '?' (1 character).
  • id array of strings (optional) If provided, results must have project IDs among the provided list of IDs. The array may have no more than 1000 elements.
  • billTo string or array of strings (optional) If a string, then the result set will contain only projects whose billTo matches the string. If an array, then the result set will contain only projects whose billTo is one of the specified strings.
  • region string or array of strings (optional) If a string, then the result set will contain only projects whose region matches the string. If an array, then the result set will contain only projects whose region is one of the specified strings.
  • tags string or mapping (optional) Defined by grammar below, represents the tag(s) any results must have
    • tags ::= < string >
    • tags ::= {"$and": tagsArray}
    • tags ::= {"$or": tagsArray}
    • tagsArray ::= [ ]
    • tagsArray ::= [tags, ...]
  • properties mapping (optional) Defined by grammar below. If provided, each matching result must have the specified properties. Each "key" is a property name, and each "value" may either be a string (meaning that the key must have the specified value) or the boolean true (meaning that the specified key must be present but may have any value).
    • constraint ::= { key: value, ... }
    • constraint ::= { "$and": constraintArray }
    • constraint ::= { "$or": constraintArray }
    • constraintArray ::= [ ]
    • constraintArray ::= [constraint, ...]
  • level string (optional, default "CONTRIBUTE") Must be one of "VIEW", "UPLOAD", "CONTRIBUTE", or "ADMINISTER" to represent the minimum permissions level of the project results to be returned
  • explicitPermission boolean (optional) If a value of true is provided, then the results will be restricted to projects for which there is at least one explicit or implicit permission. If false, then the results will be restricted to public projects for which the user has neither explicit nor implicit permissions
  • public boolean (optional) If set to true, then only public projects will be included in result. If false, then no public project will be included in result.
  • created mapping (optional) If at least one of the following keys is specified, the resulting projects must have been created in the indicated time frame. If not specified, there will be no constraint on project creation time. If a created hash does not contain at least one of the following keys, an error will be thrown.
    • after timestamp (optional) If specified, only return results created at or after this time
    • before timestamp (optional) If specified, only return results created at or before this time
  • describe boolean or mapping (optional, default false) False indicates that no extra metadata should be retrieved with the results. A mapping represents the input that would be used for calling /project-xxxx/describe on each of the returned results; a value of true is equivalent to the empty hash input.
  • starting string (optional) Continue a previous query that had reached its limit; the value that was returned as next in the query's output should be provided here
  • containsPHI boolean (optional) If set to true, only projects that contain PHI data will be retrieved. If set to false, only projects that do not contain PHI data will be retrieved.
  • limit int (optional, default 1000) Maximum number of results that may be returned; must be between 1 and 1000 (inclusive)
  • sharedWith string (optional) If specified, the results will be restricted to projects that are explicitly shared with the specified user ID, organization ID, or the string "PUBLIC" for public projects

Outputs

  • results array of mappings List of results, each with the following fields:

    • id string ID of the result
    • level string Maximal permission level (one of "VIEW", "UPLOAD", "CONTRIBUTE", "ADMINISTER") held by the requesting user/job (either directly or through an organization)
    • permissionSources array of strings (present only if an unrestricted login token is used to make this API call) IDs of the source(s) that were granted the maximal permission level level through which the requesting user has access. Possible values are the user's ID, organization IDs, or the string "PUBLIC" for public projects
    • public boolean Whether the project is public

    If describe was set to true or a mapping:

    • describe mapping The output of the result's corresponding describe method
  • next string or null If null, all results were reported in results. If a string, represents the next result that could not be returned because limit results have already been returned. This value should be passed directly to starting in a subsequent query if more results are desired.

Errors

See Errors (Protocols)

API method: /system/findProjectMembers

Specification

Returns a list of all the members (user, team, or organization) of a project.

Note: "PUBLIC" is never included in the list of project members; instead, the output hash contains a boolean value public to indicate whether the project is public

Ordering of results is:

  • Ascending by member ID.

Inputs

  • project string ID of the project
  • level string (optional, default "VIEW") Must be one of "VIEW", "UPLOAD", "CONTRIBUTE", or "ADMINISTER", to represent the minimum permissions level that the members must have (granted directly to them)
  • describe boolean (optional, default false) Whether describe should be called for all results
  • starting string (optional) Continue a previous query that had reached its limit; the value that was returned as next in the query's output should be provided here
  • limit int (optional, default 1000) Maximum number of results that may be returned; must be between 1 and 1000 (inclusive)

Outputs

  • results array of mappings List of results, each with the following fields:

    • id string ID of the project member
    • level string Permission level for the given project granted directly to the member

    If describe was set to true:

    • describe mapping Metadata about the project member, containing the following fields:

      • id string ID of the member
      • class string Either "user" or "org"
      • permittedRegions array of strings The regions this member can operate in

      The following keys are present if class is "user":

      • first string The user's first name
      • last string The user's last name
      • middle string The user's middle name
      • handle string The user's username or handle

      The following key is present if class is "org":

      • name string Organization name
  • public boolean Whether the project is public

  • next string or null If null, all results were reported in results. If a string, represents the next result that could not be returned because limit results have already been returned. This value should be passed directly to starting in a subsequent query if more results are desired.

Errors

  • InvalidInput
    • The input is not a hash
    • level, if provided, is not a recognized permissions level
  • PermissionDenied
    • VIEW access to the project is required

API method: /system/findOrgs

Specification

Lists orgs in which the requesting user has at least the specified membership level, subject to additional query constraints.

Ordering of results

Orgs will be returned in ascending order by their IDs.

Inputs

  • id array of strings (optional) If provided, results will be limited to the org IDs included in the array. The array may have no more than 1000 elements.
  • level string one of "ADMIN" or "MEMBER". The results will contain only orgs in which the requesting user has at least the specified membership level.
  • allowBillableActivities boolean (optional) if a boolean, then the results will contain only orgs in which the requesting user either has (true) or does not have (false) the allowBillableActivities membership permission.
  • describe boolean or mapping (optional; default false) if a mapping, then it represents the input that will be used to describe each of the results; true indicates that the empty mapping will be used. A value of false indicates that no extra metadata be retrieved with the results.
  • starting mapping (optional) mapping used to continue a previous query that had reached its limit; the non-null value that was returned as next in the output of that query should be specified here.
  • limit int (optional; default 1000) maximum number of results that may be returned; must be between 1 and 1000 (inclusive)

Outputs

  • results array of mappings list of results, each with the following fields:

    • id string org ID.

    If describe was a mapping or true, then each result will contain the following additional fields:

    • describe mapping the output of describing the corresponding org.
  • next mapping or null if null, then all results were returned in results; otherwise, represents the next result that could not be returned because limit results have already been returned. If a mapping, then this value should be specified as the starting input in a subsequent query if more results are desired.

Errors

  • PermissionDenied
    • The requesting user does not have a full scope token

See Errors (Protocols)

Last edited by Calvin Bao, 2017-04-11 16:26:31

 Feedback