.. _queries: ======= Queries ======= Abstract ======== This section details the queries supported by this module. Query Format ============ Unlike the queries used in the **nexiles|gateway** core, this plug-in uses a *structured* query format. Queries need to be given as **JSON Objects**. We support passing queries: - as *URL Parameter* - in the request body URL Parameter ------------- To support easy testing and manual queries using a web browser, the plug-in supports queries specified as URL parameter. Multiple queries are accepted, they are aggregated into one composite query. Examples (only the query part is shown):: .../services/query/1.0/query?q={"name":"*.prt"} .../services/query/1.0/query?q={"type":"wt.part.WTPart","name":"*.prt"} .../services/query/1.0/query?q={"number":"0815*"}&q={"type":"wt.part.WTPart","name":"*.prt"} .../services/query/1.0/query?q={"name":"269*.asm","config_spec":"latest"} Request Body ------------ For automated uses it is easier to specify the query in the request body. .. note:: Be sure that you specify the correct mime type in the HTTP header `application/json` Example (matches the third query from the URL parameter example):: { "qq": [ { "number": "0815*" } , { "type": "wt.part.WTPart" "name": "*.prt" } ] } Query Filters ============= All the query filters supported by the **nexiles|gateway** core query module are supported. Config Specs ============ The user of this plug-in can make use of **config specs**. These are additional filters which are processed on the server and filter the result set in certain ways. Config specs are passed as `config_spec` key in the query. The *value* of this key specifies the config spec, e.g:: "config_spec": "<>" Some config specs take arguments, which are passed after the type separated by pipes (`|`):: "config_spec": "<>|<>|<>|...." .. note:: Config Specs can **not** be combined. .. note:: Some Config Specs are usable only on certain **types**. config spec: Latest ------------------- :allowed types: `Iterated` types :type `latest` :arguments: none example: `"config_spec": "latest"` Returns, in priority order, the latest iteration for a master owned by the current principal, the latest iteration by comparing the iterationIdentifier's series value if not owned by the current principal, or the latest by create Timestamp if the series values are equivalent. Note that only one iteration is returned for any given master. config spec: Life Cycle State ----------------------------- :allowed types: things which have a *life cycle* :type `lifecycle` :arguments: the life cycle name example: `"config_spec": "lifecycle|INWORK"` This config spec filters the result set for a given **life cycle state**. Original WT10 docs: The LifeCycleConfigSpec can be applied to LifeCycleManaged elements to filter them based on life cycle state. Only those elements at the specified life cycle state will be returned. config spec: Folder ------------------- :allowed types: things which have are *Foldered* :type `folder` :arguments: The `OID` of a `Folder` object, or a cabinet based object. example: `"config_spec": "folder|OR:wt.folder.Cabinet:12345"` The IteratedFolderedConfigSpec can be used to filter IteratedFoldered elements based on folder location. Only those elements in the particular folder or sub-folder will be returned by this ConfigSpec. Uf the OID passed resolves to a object which implements the 'Folder' interface, then this object is used, else a method `getDefaultCabinet` is queried to fetch the default cabinet of the object. This is means that one can pass e.g. a *Product*, a *Library* etc. and the config spec works as expected. Fields and Associations ======================= Often it's application dependent how much information about each of the results is actually needed. Per default the query plug-in only reports a minimal set of values per query result to keep the response time down. If an application needs more information, then it can specify **fields** and **associations** along with the query. **fields** This specifies the **attributes** which are read from the resulting object. Please note, this only works for **simple object attributes**. If a attribute is not found, then `null` is returned. **associations** This specifies the *associations* which should be returned **per result object**. This is *expensive* in terms of processing time on the server -- so be careful. .. _queries_fields: Fields ====== Field examples -------------- .. note:: For a comprehensive list refer to the Windchill java docs and look for simple attributes. +----------------------------+------------------------------------------+-----------------------+ | field name | description | object type | +============================+==========================================+=======================+ | name | the `name` attribute | e.g. `EPMDocument` | +----------------------------+------------------------------------------+-----------------------+ | CADName | the `CADName` attribute | e.g. `EPMDocument` | +----------------------------+------------------------------------------+-----------------------+ | latestIteration | the `latestIteration` attribute | all `Iterated` types | +----------------------------+------------------------------------------+-----------------------+ | state | the Life Cycle State attribute | all `Iterated` types | +----------------------------+------------------------------------------+-----------------------+ | location | the folder the object is located in | all `Foldered` types | +----------------------------+------------------------------------------+-----------------------+ | folderPath | path of the object in it's container | all `Foldered` types | +----------------------------+------------------------------------------+-----------------------+ | containerName | the name of the container of this object | all `Contained` types | +----------------------------+------------------------------------------+-----------------------+ | versionDisplayIdentifier | the `version` | all `Versioned` types | +----------------------------+------------------------------------------+-----------------------+ | iterationDisplayIdentifier | the `iteration` | all `Versioned` types | +----------------------------+------------------------------------------+-----------------------+ .. note:: The example `latestIteration` is actually a flag returned by the method `isLatestIteration()` -- but we can only use **values** not **methods**. Example Query ------------- Consider the following query:: http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/query/1.0/query?limit=5&q={"name":"SQ*.prt%"}&field=name&field=CADName&field=latestIteration&field=number Here, we ask for all `EPMDocument` types which have a `name` attribute like `SQ*.prt`, and we'd like *additionally* see the attributes `name`, `number`, `CADName` and `isLatestIteration`. .. note:: For easier debugging and testing, we also allow to specify the fields URL parameter. Note that there the name is **singular** because URL parameter can be specified multiple times. The JSON post body parameter is called `fields` (**plural**). Here's the result (shortened, formatted):: { url: "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/query/1.0/query/190952?start=0&limit=5&page=0", next: "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/query/1.0/query/190952?start=0&limit=5&page=1", session: 190952, start: 0, count: 5, success: true, limit: 5, page: 0, pos: 0, total_count: 433, items: [ { url: "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/api/1.0/epmdocuments/OR:wt.epm.EPMDocument:48430", latestIteration: true, CADName: "sqb.prt", number: "SQB.PRT", details: "http://windchill.virtual.nexiles.com/Windchill/app/#ptc1/tcomp/infoPage?oid=OR:wt.epm.EPMDocument:48430&u8=1", oid: "OR:wt.epm.EPMDocument:48430", name: "sqb.prt" }, { url: "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/api/1.0/epmdocuments/OR:wt.epm.EPMDocument:49045", latestIteration: true, CADName: "sqb001.prt", number: "SQB001.PRT", details: "http://windchill.virtual.nexiles.com/Windchill/app/#ptc1/tcomp/infoPage?oid=OR:wt.epm.EPMDocument:49045&u8=1", oid: "OR:wt.epm.EPMDocument:49045", name: "sqb001.prt" }, { url: "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/api/1.0/epmdocuments/OR:wt.epm.EPMDocument:48588", latestIteration: true, CADName: "sqb002.prt", number: "SQB002.PRT", details: "http://windchill.virtual.nexiles.com/Windchill/app/#ptc1/tcomp/infoPage?oid=OR:wt.epm.EPMDocument:48588&u8=1", oid: "OR:wt.epm.EPMDocument:48588", name: "sqb002.prt" }, { url: "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/api/1.0/epmdocuments/OR:wt.epm.EPMDocument:48771", latestIteration: true, CADName: "sqb003.prt", number: "SQB003.PRT", details: "http://windchill.virtual.nexiles.com/Windchill/app/#ptc1/tcomp/infoPage?oid=OR:wt.epm.EPMDocument:48771&u8=1", oid: "OR:wt.epm.EPMDocument:48771", name: "sqb003.prt" }, { url: "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/api/1.0/epmdocuments/OR:wt.epm.EPMDocument:48667", latestIteration: true, CADName: "sqb004.prt", number: "SQB004.PRT", details: "http://windchill.virtual.nexiles.com/Windchill/app/#ptc1/tcomp/infoPage?oid=OR:wt.epm.EPMDocument:48667&u8=1", oid: "OR:wt.epm.EPMDocument:48667", name: "sqb004.prt" } ] } Associations ============ Associations are used in e.g. ExtJS to model data structures which have *associations*. In Windchill, we have multiple associations, which are type specific. Examples: **IBA Attributes** Some object may have *IBA Attributes*. **Secondary Content** Objects which implement the `ContentHolder` interface may have multiple content objects. **Representations** Objects which implement the `Representable` interface may have multiple *representations* (viewables). Association Keys ---------------- +-------------------+---------------------------------------+----------------------------------------------------+-------------------------+ | assoc key | description | remark | status | +===================+=======================================+====================================================+=========================+ | `ibas` | IBA attributes | Only `EPMDocument` types ATM | **draft** | +-------------------+---------------------------------------+----------------------------------------------------+-------------------------+ | `content` | content files | objects implementing the `ContentHolder` interface | **draft** | +-------------------+---------------------------------------+----------------------------------------------------+-------------------------+ | `vault_info` | vault file info | objects implementing the `ContentHolder` interface | **draft** | +-------------------+---------------------------------------+----------------------------------------------------+-------------------------+ | `files` | content files using file service URLs | objects implementing the `ContentHolder` interface | **draft** | +-------------------+---------------------------------------+----------------------------------------------------+-------------------------+ | `representations` | representations | objects implementing the `Representable` interface | **draft** | +-------------------+---------------------------------------+----------------------------------------------------+-------------------------+ | `versions` | version history | objects implementing the `Iterated` interface | **not yet implemented** | +-------------------+---------------------------------------+----------------------------------------------------+-------------------------+ | `iterations` | iteration history | objects implementing the `Iterated` interface | **not yet implemented** | +-------------------+---------------------------------------+----------------------------------------------------+-------------------------+ Example query ------------- Please consider the following query:: http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/query/1.0/query?q={"name":"SQ*.prt"}&field=name&field=CADName&field=latestIteration&assoc=ibas&assoc=representations&limit=5 Here we again ask for `EPMDocument` types matching a certain name pattern, include some additional fields (see above). This time, we asked for the associations `ibas` and `representations`. .. note:: For easier debugging and testing, we also allow to specify the associations as URL parameter. Note that for the URL parameter the key is `assoc` (**singular**) since that parameter can be specified multiple times. The JSON post body parameter is called `associations` (**plural**). This is the (shortened, only one result shown) result. Things to notice: - A association returns a empty list if it contains no objects. This is also true if the association does not match the result type. - The runtime (`_runtime` field) is considerably higher. In this example the back end needed to fetch all representations for the page results. - Associations are **not** cached -- if you request a page ten times, the associations are calculated ten times. :: { _runtime: 1.20300006866455078, count: 5, url: "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/query/1.0/query/191313?start=0&limit=5&page=0", next: "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/services/query/1.0/query/191313?start=0&limit=5&page=1", query: { associations: [ "ibas", "representations" ], fields: [ "name", "CADName", "latestIteration" ], qq: [ { name: "SQ*.prt" } ] }, start: 0, success: true, limit: 5, page: 0, pos: 0, total_count: 433, items: [ { url: "http://windchill.virtual.nexiles.com/Windchill/servlet/nexiles/tools/api/1.0/epmdocuments/OR:wt.epm.EPMDocument:48430", details: "http://windchill.virtual.nexiles.com/Windchill/app/#ptc1/tcomp/infoPage?oid=OR:wt.epm.EPMDocument:48430&u8=1", oid: "OR:wt.epm.EPMDocument:48430", name: "sqb.prt", latestIteration: true, CADName: "sqb.prt", ibas: [ ], representations: [ { url: "http://windchill.virtual.nexiles.com/Windchill/servlet/WindchillAuthGW/wt.content.ContentHttp/viewContent/wvspvp.pvp?u8&HttpOperationItem=wt.content.ApplicationData%3A88944&ContentHolder=wt.viewmarkup.DerivedImage%3A88929&originalFileName=wvspvp.pvp&forceDownload=true", role: "PRODUCT_VIEW_EDP", filename: "wvspvp.pvp", name: "Demo" }, { url: "http://windchill.virtual.nexiles.com/Windchill/servlet/WindchillAuthGW/wt.content.ContentHttp/viewContent/sqb_prt.pvm?u8&HttpOperationItem=wt.content.ApplicationData%3A88953&ContentHolder=wt.viewmarkup.DerivedImage%3A88929&originalFileName=sqb_prt.pvm&forceDownload=true", role: "PRODUCT_VIEW_EDM", filename: "sqb_prt.pvm", name: "Demo" }, { url: "http://windchill.virtual.nexiles.com/Windchill/servlet/WindchillAuthGW/wt.content.ContentHttp/viewContent/sqb_prt_small.jpg?u8&HttpOperationItem=wt.content.ApplicationData%3A88938&ContentHolder=wt.viewmarkup.DerivedImage%3A88929&originalFileName=sqb_prt_small.jpg&forceDownload=true", role: "THUMBNAIL_SMALL", filename: "sqb_prt_small.jpg", name: "Demo" }, { url: "http://windchill.virtual.nexiles.com/Windchill/servlet/WindchillAuthGW/wt.content.ContentHttp/viewContent/sqb_prt.pvs?u8&HttpOperationItem=wt.content.ApplicationData%3A88956&ContentHolder=wt.viewmarkup.DerivedImage%3A88929&originalFileName=sqb_prt.pvs&forceDownload=true", role: "PRODUCT_VIEW_ED", filename: "sqb_prt.pvs", name: "Demo" }, { url: "http://windchill.virtual.nexiles.com/Windchill/servlet/WindchillAuthGW/wt.content.ContentHttp/viewContent/sqb_prt.pvt?u8&HttpOperationItem=wt.content.ApplicationData%3A88941&ContentHolder=wt.viewmarkup.DerivedImage%3A88929&originalFileName=sqb_prt.pvt&forceDownload=true", role: "THUMBNAIL3D", filename: "sqb_prt.pvt", name: "Demo" }, { url: "http://windchill.virtual.nexiles.com/Windchill/servlet/WindchillAuthGW/wt.content.ContentHttp/viewContent/sqb_prt.ol?u8&HttpOperationItem=wt.content.ApplicationData%3A88950&ContentHolder=wt.viewmarkup.DerivedImage%3A88929&originalFileName=sqb_prt.ol&forceDownload=true", role: "SECONDARY", filename: "sqb_prt.ol", name: "Demo" }, { url: "http://windchill.virtual.nexiles.com/Windchill/servlet/WindchillAuthGW/wt.content.ContentHttp/viewContent/sqb_prt.pva?u8&HttpOperationItem=wt.content.ApplicationData%3A88947&ContentHolder=wt.viewmarkup.DerivedImage%3A88929&originalFileName=sqb_prt.pva&forceDownload=true", role: "SECONDARY", filename: "sqb_prt.pva", name: "Demo" }, { url: "http://windchill.virtual.nexiles.com/Windchill/servlet/WindchillAuthGW/wt.content.ContentHttp/viewContent/sqb_prt.jpg?u8&HttpOperationItem=wt.content.ApplicationData%3A88935&ContentHolder=wt.viewmarkup.DerivedImage%3A88929&originalFileName=sqb_prt.jpg&forceDownload=true", role: "THUMBNAIL", filename: "sqb_prt.jpg", name: "Demo" } ] }, ... ] } .. _macro_expansion: Macro Expansion =============== Some queries are very cumbersome for the end-user to specify. Therefore, the query plugin supports **macros**. +----------------+------------+-----------------------------------------+ | macro key | parameters | description | +================+============+=========================================+ | `@folder_path` | `context` | Expands into a series of folder queries | +----------------+------------+-----------------------------------------+ Macro: folder_path ------------------ This macro expands into a series of folder queries such that the query will limit itself to objects **below or in** the given folder path. Example -- find all assemblies below `/Default/1_CoreAndFrame` of the given context:: { "qq": [ "@folder_path": "/Default/1_CoreAndFrame", "context": "OR:wt.inf.library.WTLibrary:3204656", "name": "*.asm" ], "fields": [ ... ] } .. _query_options: Query Options ============= You can set these global options on a query using the `options` key: +--------------+------------------------------------+ | option | description | +==============+====================================+ | `adminquery` | Execute query as **administrator** | +--------------+------------------------------------+ .. vim: set ft=rst tw=75 nocin nosi ai sw=4 ts=4 expandtab: