5 Service Sets ToC Previous Next

5.9 Query Service Set ToC Previous Next

5.9.3 QueryFirst ToC Previous Next

5.9.3.1 Description ToC

This Service is used to issue a Query request to the Server. The complexity of the Query can range from very simple to highly sophisticated. The Query can simply request data from instances of a TypeDefinitionNode or TypeDefinitionNode subject to restrictions specified by the filter. On the other hand, the Query can request data from instances of related Node types by specifying a RelativePath from an originating TypeDefinitionNode. In the filter, a separate set of paths can be constructed for limiting the instances that supply data. A filtering path can include multiple RelatedTo operators to define a multi-hop path between source instances and target instances. For example, one could filter on students that attend a particular school, but return information about students and their families. In this case, the student school relationship is traversed for filtering, but the student family relationship is traversed to select data. For a complete description of ContentFilter see 7.4, also see Clause B.1 for simple examples and Clause B.2 for more complex examples of content filter and queries.

The Client provides an array of NodeTypeDescription which specify the NodeId of a TypeDefinitionNode and selects what Attributes are to be returned in the response. A Client can also provide a set of RelativePaths through the type system starting from an originating TypeDefinitionNode. Using these paths, the Client selects a set of Attributes from Nodes that are related to instances of the originating TypeDefinitionNode. Additionally, the Client can request the Server return instances of subtypes of TypeDefinitionNodes. If a selected Attribute does not exist in a TypeDefinitionNode but does exist in a subtype, it is assumed to have a null value in the TypeDefinitionNode in question. Therefore, this does not constitute an error condition and a null value is returned for the Attribute.

The Client can use the filter parameter to limit the result set by restricting Attributes and Properties to certain values. Another way the Client can use a filter to limit the result set is by specifying how instances should be related, using RelatedTo operators. In this case, if an instance at the top of the RelatedTo path cannot be followed to the bottom of the path via specified hops, no QueryDataSets are returned for the starting instance or any of the intermediate instances.

When querying for related instances in the RelativePath, the Client can optionally ask for References. A Reference is requested via a RelativePath that only includes a ReferenceType. If all References are desired than the root ReferenceType is listed. These References are returned as part of the QueryDataSets.

Query Services allow a special handling of the targetName field in the RelativePath. In several Query use cases a type NodeId is necessary in the path instead of a QualifiedName. Therefore the Client is allowed to specify a NodeId in the QualifiedName. This is done by setting the namespaceIndex of the targetName to zero and the name part of the targetName to the XML representation of the NodeId. The XML representation is defined in OPC 10000-6. When matching instances are returned as the target node, the target node shall be an instance of the specified type or subtype of the specified type.

Table 47 defines the request parameters and Table 48 the response parameters for the QueryFirst Service.

Table 47 – QueryFirst Request Parameters

Name Type Description
Request    
   requestHeader RequestHeader Common request parameters (see 7.28 for RequestHeader definition).
   View ViewDescription Specifies a View and temporal context to a Server (see 7.39 for ViewDescription definition).
   nodeTypes [] NodeTypeDescription This is the Node type description. This structure is defined in-line with the following indented items.
      typeDefinitionNode ExpandedNodeId NodeId   of the originating TypeDefinitionNode of the instances for which data is to be returned.
      includeSubTypes Boolean A flag that indicates whether the Server should include instances of subtypes of the TypeDefinitionNode in the list of instances of the Node type.
      dataToReturn [] QueryDataDescription Specifies an Attribute or Reference from the originating typeDefinitionNode along a given relativePath for which to return data. This structure is defined in-line with the following indented items.
         relativePath RelativePath Browse path relative to the originating Node that identifies the Node which contains the data that is being requested, where the originating Node is an instance Node of the type defined by the type definition Node. The instance Nodes are further limited by the filter provided as part of this call. For a definition of relativePath see 7.26.
This relative path could end on a Reference, in which case the ReferenceDescription of the Reference would be returned as its value.
The targetName field of the relativePath may contain a type NodeId. This is done by setting the namespaceIndex of the targetName to zero and the name part of the targetName to the XML representation of the NodeId. The XML representation is defined in OPC 10000-6.
When matching instances are returned as the target node, the target node shall be an instance of the specified type or subtype of the specified type.
         attributeId IntegerId Id of the Attribute. This shall be a valid Attribute Id. The IntegerId is defined in 7.14. The IntegerId for Attributes are defined in OPC 10000-6. If the RelativePath ended in a Reference then this parameter is 0 and ignored by the server.
         indexRange NumericRange This parameter is used to identify a single element of a structure or an array, or a single range of indexes for arrays. If a range of elements are specified, the values are returned as a composite. The first element is identified by index 0 (zero). The NumericRange type is defined in 7.22.
This parameter is null if the specified Attribute is not an array or a structure. However, if the specified Attribute is an array or a structure, and this parameter is null, then all elements are to be included in the range.
   Filter ContentFilter Resulting Nodes shall be limited to the Nodes matching the criteria defined by the filter. ContentFilter is discussed in 7.4. If an empty filter is provided then the entire AddressSpace shall be examined and all Nodes that contain a matching requested Attribute or Reference are returned.
   maxDataSetsToReturn Counter The number of QueryDataSets that the Client wants the Server to return in the response and on each subsequent continuation call response. The Server is allowed to further limit the response, but shall not exceed this limit.
A value of 0 indicates that the Client is imposing no limitation.
   maxReferencesToReturn Counter The number of References that the Client wants the Server to return in the response for each QueryDataSet and on each subsequent continuation call response. The Server is allowed to further limit the response, but shall not exceed this limit.
A value of 0 indicates that the Client is imposing no limitation.
For example a result where 4 Nodes are being returned, but each has 100 References, if this limit were set to 50 then only the first 50 References for each Node would be returned on the initial call and a continuation point would be set indicating additional data.

Table 48 – QueryFirst Response Parameters

Name Type Description
Response    
   responseHeader ResponseHeader Common response parameters (see 7.29 for ResponseHeader definition).
   queryDataSets [] QueryDataSet The array of QueryDataSets. This array is empty if no Nodes or References met the nodeTypes criteria. In this case the continuationPoint parameter shall be empty.
The QueryDataSet type is defined in 7.23.
   continuationPoint ContinuationPoint Server-defined opaque value that identifies the continuation point.
The continuation point is used only when the Query results are too large to be returned in a single response. “Too large” in this context means that the Server is not able to return a larger response or that the number of QueryDataSets to return exceeds the maximum number of QueryDataSets to return that was specified by the Client in the request.
The continuation point is used in the QueryNext Service. When not used, the value of this parameter is null. If a continuation point is returned, the Client shall call QueryNext to get the next set of QueryDataSets or to free the resources for the continuation point in the Server.
A continuation point shall remain active until the Client passes the continuation point to QueryNext or the session is closed. If the maximum continuation points have been reached the oldest continuation point shall be reset.
The ContinuationPoint type is described in 7.6.
   parsingResults[] ParsingResult List of parsing results for QueryFirst. The size and order of the list matches the size and order of the NodeTypes request parameter. This structure is defined in-line with the following indented items.
This list is populated with any status codes that are related to the processing of the node types that are part of the query. The array can be empty if no errors where encountered. If any node type encountered an error all node types shall have an associated status code.
      statusCode StatusCode Parsing result for the requested NodeTypeDescription.
      dataStatusCodes [] StatusCode List of results for dataToReturn. The size and order of the list matches the size and order of the dataToReturn request parameter. The array can be empty if no errors where encountered.
      dataDiagnosticInfos [] DiagnosticInfo List of diagnostic information dataToReturn (see 7.8 for DiagnosticInfo definition). The size and order of the list matches the size and order of the dataToReturn request parameter. This list is empty if diagnostics information was not requested in the request header or if no diagnostic information was encountered in processing of the query request.
   diagnosticInfos [] DiagnosticInfo List of diagnostic information for the requested NodeTypeDescription. This list is empty if diagnostics information was not requested in the request header or if no diagnostic information was encountered in processing of the query request.
   filterResult ContentFilter
Result
A structure that contains any errors associated with the filter.
This structure shall be empty if no errors occurred.
The ContentFilterResult type is defined in 7.4.2.

5.9.3.2 Service results ToC

If the Query is invalid or cannot be processed, then QueryDataSets are not returned and only a Service result, filterResult, parsingResults and optional DiagnosticInfo is returned. Table 49 defines the Service results specific to this Service. Common StatusCodes are defined in Table 177.

Table 49 – QueryFirst Service Result Codes

Symbolic Id Description
Bad_NothingToDo See Table 177 for the description of this result code.
Bad_TooManyOperations See Table 177 for the description of this result code.
Bad_ContentFilterInvalid See Table 178 for the description of this result code.
Bad_ViewIdUnknown See Table 177 for the description of this result code.
Bad_ViewTimestampInvalid See Table 177 for the description of this result code.
Bad_ViewParameterMismatchInvalid See Table 177 for the description of this result code.
Bad_ViewVersionInvalid See Table 177 for the description of this result code.
Bad_InvalidFilter The provided filter is invalid, see the filterResult for specific errors
Bad_NodelistError The NodeTypes provided contain an error, see the parsingResults for specific errors
Bad_InvalidView The provided ViewDescription is not a valid ViewDescription.
Good_ResultsMayBeIncomplete The Server should have followed a reference to a node in a remote Server but did not. The result set may be incomplete.

5.9.3.3 StatusCodes ToC

Table 50 defines values for the parsingResults statusCode parameter that are specific to this Service. Common StatusCodes are defined in Table 178.

Table 50 – QueryFirst Operation Level Result Codes

Symbolic Id Description
Bad_NodeIdInvalid See Table 178 for the description of this result code.
Bad_NodeIdUnknown See Table 178 for the description of this result code.
Bad_NotTypeDefinition The provided NodeId was not a type definition NodeId.
Bad_AttributeIdInvalid See Table 178 for the description of this result code.
Bad_IndexRangeInvalid See Table 178 for the description of this result code.

Previous Next