Skip to main content
Version: 8.1

system.tag.query

New in 8.1.19

This function is used in Python Scripting.

Description

Queries a Tag Provider to produce a list of tags that meet the specified criteria. Provides the same functionality as the Tag Report Tool.

note

Properties contained within a set or properties that are a set require wildcards around search terms when using Like and Not Like. These properties are listed below.

  • Alarms (Only returns results when searching for alarm names)
  • Parameters
  • Qualified Value
  • Read Permissions
  • Tag Event Scripts
  • Value (If the value data type is a set)
  • Write Permissions

Client Permission Restrictions

This scripting function has no Client Permission restrictions.

Syntax

note

This function accepts keyword arguments.

system.tag.query([provider], [query], [limit], [continuation])

Parameters

TypeParameterDescription
StringproviderThe Tag Provider to query.

Note: Technically, this parameter is optional, but omitting it will result in an empty Results object. [optional]
PyObjectqueryAn object that specifies the query conditions. Can be configured in the Tag Report Tool using the Copy as Script function. See example below. [optional]
IntegerlimitMaximum results to return. If more results are possible, the result will have a continuation point set. [optional]
StringcontinuationThe tag ID of a previously returned continuation point, to continue the associated query from that point [optional]

Returns

Results - A Results object which contains a list of tag dictionaries, one for each tag found during the browse. See Scripting Object Reference.

Scope

Gateway

Code Examples

Example #1
provider = 'Sample_Tags'
limit = 100

query = {
"condition": {
"path": "Ramp/Ramp*",
"tagType": "AtomicTag",
"attributes": {
"values": [
"alarm"
],
"requireAll": True
},
"valueSource": "opc",
"quality": "Error"
},
"returnProperties": [
"path",
"tagType",
"quality"
]
}

# Limited to 100 rows. Use continuation functionality to continue from last result,
# or remove limit for full results.
results = system.tag.query(provider, query, limit)
for result in results:
print(result)


# To continue from last result, use continuation
# Note: The query is stored on the gateway, and therefore does not need to be sent again.
# A query parameter will be ignored if continuation is specified.
results = system.tag.query(continuation=results.continuationPoint)
for result in results:
print(result)

New in 8.1.28

Example #2 - Using OR and AND Operators
# This example uses the "Or" operator introduced in version 8.1.28. Note that the "Or" (line 18) and "And" (line 21, line 31) operators are used in the
# JSON query parameter, not in the system function itself.
# This example was written using the Tag Report Tool's "Copy as Script" functionality.

provider = 'default'
limit = 100

query = {
"options": {
"includeUdtMembers": True,
"includeUdtDefinitions": False
},
"condition": {
"attributes": {
"values": [],
"requireAll": True
},
"properties": {
"op": "Or",
"conditions": [
{
"op": "And",
"conditions": [
{
"prop": "name",
"comp": "Like",
"value": "*tag*"
}
]
},
{
"op": "And",
"conditions": [
{
"prop": "name",
"comp": "Like",
"value": "*1*"
}
]
}
]
}
},
"returnProperties": [
"tagType",
"quality"
]
}

# Limited to 100 rows. Use continuationPoint functionality to continue from last result,
# or remove limit for full results.
results = system.tag.query(provider, query, limit)

Keywords

system tag query, tag.query