Queries
Use queries to retrieve design-time and run-time objects.
You can retrieve design-time objects from a Model repository or run-time objects that were deployed to a Data Integration Service. To construct a query, use query parameters to determine the objects that you want to retrieve. You can make a query more specific by using a clause and operators.
Query Structure
Use parameters, operations, and clauses to build a query.
You can structure a query by using parameters, comparison operators, logical operators, and the Where clause.
A query is structured with the following elements:
- Query parameters
- Query parameters are categorized into subject, time, status, and location. Each query must be combined with a comparison operator. For example,
mapping=Mapping1
- Comparison operators
- Comparison operators are used to specify criteria to query objects. Comparison operators are used with the query parameters to build a query.
- Logical operators
- Logical operators are used to test a condition in a query. Logical operators can have multiple query parameters. For example,
mapping=Mapping1 || createdBy=admin
- Where clause
- The Where clause is used when you want to restrict the query scope. For example,
name=mapping1 where project=project1, folder=folder1.
Query Parameters
Use query parameters for subject, time, status, and location to build a query.
Query parameters are used to query design-time objects in a Model repository and run-time objects that are deployed to a Data Integration Service.
Query parameters are divided into the following parameters types:
- Subject
- Parameters that tests a subject such as specific object or user.
Parameter | Object Type | Description |
|---|
name | Design-time object | Name of the object that you want to query. You can specify the name of one of the following types of objects: - - Mapping
- - Physical data object
- - Parameter set
|
tag | Design-time object | Tag that is assigned to the object. |
createdBy | Design-time object | User that created the object. |
lastModifiedBy | Design-time object | User that last modified the object. |
name | Run-time object | Name of the object that you want to query. You can specify the name of the following type of objects: - - Mapping
- - Physical data object
- - Parameter set
|
- Time
- Parameters that tests the time when an object was changed.
Parameter | Object Type | Description |
|---|
lastModifiedTime | Design-time object | Time that the object was last modified. |
checkInTime | Design-time object | Time that the object was last checked in. |
checkOutTime | Design-time object | Time that the object was last checked out. |
- Status
- Parameters that tests the status of an object.
Parameter | Object Type | Description |
|---|
versionStatus | Design-time object | Version status of the object. The version status can either be checked in or checked out. |
- Location
- Parameters that tests where an object is located such as specific project, folder, or run-time application.
Parameter | Object Type | Description |
|---|
folder | Design-time object | Folder that contains the object. |
project | Design-time object | Project that contains the object. |
application | Run-time object | Name of the run-time application that contains the objects. |
Comparison Operators
Lists the comparison operators that you can use to build a query.
You can use comparison operators to make that query parameter more meaningful.
The following table lists the comparison operators that you can use to specify criteria when you query objects:
Query Parameter Type | Includes Query Parameters | Comparison Operators | Examples |
|---|
Subject | name tag createdBy lastModifiedBy | ~contains~ ~not-contains~ ~not-ends-with~ ~not-starts-with~ ~ends-with~ ~starts-with~ = != ~in~ ~not-in~ | name ~contains~ Mapping tag ~in~ (tg_1, tg_2, tg_3) createdBy = Administrator lastModifiedBy ~ends-with~ visitor |
Time | lastModifiedTime checkInTime checkOutTime | > < ~within-last~ ~between~ ~not-between~ | lastModifiedTime < 2019-02-26 20:32:54 checkInTime ~between~ (2018-12-26 20:32:54, 2018-05-26 20:32:54) checkOutTime ~within-last~ 10 (days) |
Status | versionStatus | ~is-checkedin~ | versionStatus ~is-checkedin~ versionStatus ~is-checkedout~ |
Location | folder project application | ~contains~ ~not-ends-with~ ~not-contains~ ~not-starts-with~ ~ends-with~ ~starts-with~ = != ~in~ ~not-in~ | name ~contains~ Mapping where project ~ends-with~ _1 lastModifiedBy ~ends-with~ trator where folder ~not-in~ (Folder_3, Folder_2) all where project=Project_1, folder=Folder_1 name = Mapping where project=Project_1, folder=/Folder_1/Folder_2/ name = Mapping where project=Project_1, folder=/ name = captain_amaerica where app~in~ (MapGenTest, MapGenEg) |
If an object satisfies the criteria, the query returns the object to the client.
For example, if you run the query "name=mapping1" the command returns objects that have the name "mapping1."
Note: The time format is YYYY-MM-DD HH24:MI:SS.
Specifying a Folder Path
Use a recursive or non-recursive folder path to build a query.
You can specify the folder path to access objects inside a folder.
You can use the following types of folder paths:
- •Recursive. Includes all subfolders and objects inside a folder.
- •Non-recursive. Includes only the objects inside the root folder and doesn't include subfolders. The forward slash refers to the objects directly under the root folder.
The following table lists different queries with meanings:
Query | Meaning |
|---|
name=map1 folder=/ | Non-recursive. The query examines only the objects that are nested directly under the project. |
name=map1 folder=/f1/f2/ | Non-recursive. The query examines only the objects that are located in the path /f1/f2/. |
name=map1 folder=f1 | Recursive. The query examines all objects that are located in folder f1 and al subfolders within f1. |
name=map1 folder=/f1/f2 | Recursive. The query examines all objects that are located in the path /f1/f2 and all subfolders of f2. |
Note: If you use a forward slash operator to specify a folder path, you can only use the comparison operators =, !=, ~in~, and ~not-in~.
Logical Operators
Lists the logical operators that you can use to build a query.
Use logical operators to test whether one or more conditions in a query are TRUE or FALSE.
You can use the following logical operators:
Logical operator | Description | Example |
|---|
! | NOT | ! name ~not-starts-with~ M_ |
&& | AND | name ~starts-with~ map_&& lastModifiedBy ~ends-with~ visitor |
|| | OR | checkInTime > 2018-12-26 20:32:54 || lastModifiedTime > 2019-02-26 20:32:54 |
Note: You cannot use logical operators to test location query parameters, including folder names, project names, and application names.
Where Clause
Use a where clause to restrict the scope of a query.
You can specify only location query parameters inside a where clause. The location query parameters doesn't support logical operators.
Note: You cannot use logical operators, such as && or ||, inside the where clause.
For example, the following query locates a mapping within a specific project and folder:
name=mapping1 where project1, folder=folder1
You can use parentheses outside of the where clause. For example, the following query uses expressions (name contains super && name ends-with boy) and (name contains ragnarok) enclosed under parentheses and are outside of the where clause:
(name contains super && name ends-with boy) || (name contains ragnarok) where project=MapGenTest
If you want to specify only the where clause in a query, you can use the all keyword.
For example, the following query locates all objects within a specific folder:
all where folder=Folder_1