Possible error in system.tag.query documentation (8.1.19)

Ignition
,
1

Hello IA,

While learning about system.tag.query I found a possible error in the docstring.

I copied this from the pop-up

Parameters
provider: String 
Name of the tag provider to query.
query: PyObject 
A dictionary of query parameters.
limit: Integer 
Maximum size of the result set.
continuation: String 
Sets the continuation point in order to continue a query that was previously started and then limited.

But when I run the following code, nothing is returned:

provider = "TagProvider"
continuation = "sometag"
 system.tag.query(provider, continuation=continuation) 
>>> 
[]

Compared to:

provider = "TagProvider"
continuation = "sometag"
 system.tag.query(provider, continuationPoint=continuation) 
>>> 
[{u'fullPath': [TagProvider]Path/To/TagWithError, u'formatString': u'#,##0.##', u'hasChildren': False, u'dataType': Boolean, u'quality': Error_Configuration("Server "Ignition OPC-UA Server" does not exist."), u'name': u'TagWithError', u'tagType': AtomicTag, u'attributes': [alarm], u'valueSource': u'opc', u'value': [null, Error_Configuration("Server "Ignition OPC-UA Server" does not exist."), Fri Jul 29 15:58:06 PDT 2022 (1659135486177)]}, ...}]
>>>

Also, in the docs you don’t seem to agree with yourselves between the signature and the argument name, as well as the Type.

In the docs you say continuation is of type Integer while the docstring in the Designer it says String.

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

  • Parameters
    • Integer continuation- The Tag ID of a previously returned continuation point, to continue the associated query from that point [optional]

Which is it?
a. continuationPoint String
b. continuationPoint Integer
c. continuation String
d. continuation Integer

Thanks.

See:

https://docs.inductiveautomation.com/display/DOC81/system.tag.query

2

And the return type (Dataset) may also be wrong.

3

Last thing I’ll say is that the function lacks sanitization, and the Code Snippet is just bad.

The code snippet should at least produce the expected output:

for result in results:
    print str(result)  # not `results`

And on sanitization. The following code will return all tags under the Tag Provider:

provider = "Sample_Tags"

# The Tag Provider is the only required argument, but I can pass any other
# three kwargs and it will still work
results = system.tag.query(provider, testing=True, bad=True, code="i can just pass any kwarg here and it will still work")

for result in results:
    print str(result)

Is there someone from IA in this forum that could look into this?

4

Can do! I think you discovered why documenting things as they're being developed can be tricky. We'll take a look.

Side note, there's an email address listed on the footer of the docs site (docs@inductiveautomation.com). Any future issues with the documentation should go there.

1 Like
5

Thanks, @Paul.Scott!

Looking forward to the corrected version, and I’ll surely send my findings to that email address.

My main goal here is to keep ignition-api@8.1 and ignition-api-stubs as functional, and accurate as possible.

1 Like
6

Here are the answers to some of the questions you have in general:

This function returns the same object as system.tag.browse:

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

The documentation in the designer is correct. continuation is going to be a string value that is a system generated UUID that is returned when the limit parameter is used. It would be used like the following:

results = system.tag.query(provider='default', limit=10)
for result in results:
    print(results) # 1st 10 results
results = system.tag.query(continuation=results.continuationPoint)
for result in results:
    print(results) # next 10 results

The same continuation point is returned each time until the results are exhausted.

Your use of the continuationPoint kwarg and results being returned was due to the other issue you noted where unrecognized keywords are just thrown away. That is bug that our dev team should resolve.

Garth

1 Like
7

Thanks, @ggross!