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

Type	Parameter	Description
String	provider	The Tag Provider to query. Note: Technically, this parameter is optional, but omitting it will result in an empty Results object. [optional]
PyObject	query	An object that specifies the query conditions. Can be configured in the Tag Report Tool using the Copy as Script function. See example below. [optional]
Integer	limit	Maximum results to return. If more results are possible, the result will have a continuation point set. [optional]
String	continuation	The 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)