Resolving clearNamedQueryCache Silent Failure in Ignition

Symptom: Silent Return on an Invalid Path

Calling system.db.clearNamedQueryCache with a path that does not match any named query produces no error. The call completes and returns None, and execution continues past it. The function reference says a GatewayException is thrown for a malformed path, but the implementation does not throw one.

The behavior is easy to reproduce from a Perspective component event script, which runs in gateway scope:

def runAction(self, event):
    system.perspective.print("start test")
    from java.lang import Throwable
    try:
        ret = system.db.clearNamedQueryCache(path = "blablabla")
        system.perspective.print("ret: %s" % (repr(ret)))
    except Throwable as t:
        system.perspective.print("caught Throwable: %s" % (repr(t)))
    except Exception as e:
        system.perspective.print("caught Exception: %s" % (repr(e)))
    system.perspective.print("end test")
    self.props.value = 0

The expected output is caught Throwable. The actual output is start test, ret: None, end test. Neither the Java Throwable handler nor the Python Exception handler fires.

Mechanism: Void All the Way Down

The scripting function wraps internal Java methods that are declared void at every layer. Nothing below the script call reports whether a cache entry existed, whether one was evicted, or whether the path resolved to a query at all. The scripting layer therefore has nothing to return except None, and it does not validate the path before handing it down.

Three practical consequences follow:

• Success and failure look identical. A valid path with a populated cache, a valid path with caching disabled, and a typo all return None with no exception.
• try/except around the call is dead code. No exception handler around this function will ever run for a bad path, so any error UI or alarm built on that handler never fires.
• The failure surfaces later as stale data. A cache clear that silently misses leaves the old result set in place until the query's configured cache duration expires. Operators see stale values; the script log shows nothing.

The documentation and the implementation disagree. Treat the implementation as the contract: build validation outside the function rather than waiting for an exception that is not coming.

Symptoms Versus Causes

Approach Comparison

Several ways exist to get feedback out of a function that gives none. They differ in whether they work at all, what they cost at runtime, and what they catch.

Use two layers: a registry-checked wrapper at runtime, and a stale-data test at commissioning and after any named query rename or move. The wrapper stops typos from ever reaching the silent function; the test proves the path that passes the wrapper actually evicts the cache.

Recommended Guard: Registry-Checked Wrapper

Before anything else, confirm which named queries in the project have caching enabled. Only those belong in the registry; clearing a non-cached query is a no-op and signals a design mistake if it appears in code.

1. Inventory cached queries. Open each named query in the Designer and check its caching settings. Record the exact path as shown in the Named Queries tree (folder and name). Do not move on until every cached query is listed.
2. Create a project library script holding the registry and the wrapper. The script name and example path below are placeholders; replace them with your own.

   Confirm: the script saves without syntax errors and the gateway logger NQCache appears once the function is first called.

3. Replace every direct call to system.db.clearNamedQueryCache in views, event scripts, and gateway scripts with nqcache.clear(...). A project-wide search for the function name finds them. Confirm: the search returns hits only inside the library script.
4. Handle the wrapper's exceptions where the call originates. In a Perspective event:

   def runAction(self, event):
       try:
           cleared = nqcache.clear("Folder/QueryName")
           system.perspective.print("cache clear requested: %s" % cleared)
       except (ValueError, TypeError) as e:
           system.perspective.print("rejected: %s" % e)

   Confirm: passing "blablabla" now prints rejected: Unknown or uncached named query path: 'blablabla' instead of silently returning.

5. Log wording matters. The log line says "requested", not "cleared". The underlying function cannot confirm eviction, so the log must not claim it.

Pitfalls: Renames, Scope, and Argument Style

• Renaming or moving a named query breaks clears silently. Every call pointing at the old path keeps returning None while the new query's cache is never touched. With the wrapper in place, the old path is still in the registry and passes the check, so update the registry in the same change as the rename, then rerun the stale-data test.
• Argument style is not the fault. Many older system.* functions handle keyword arguments poorly, so trying the positional form is a reasonable first check. For this function, clearNamedQueryCache("blablabla") and clearNamedQueryCache(path = "blablabla") behave identically. Pick one style and keep it consistent inside the wrapper.
• Scope determines which project's cache is targeted. Perspective scripts run in gateway scope with an implied project. Gateway event scripts and scripts called from outside a project context may use a different signature; read the scope-specific syntax in the function reference for your Ignition version before reusing the wrapper there. A clear aimed at the wrong project fails exactly as silently as a typo.
• Catching java.lang.Throwable does not help. It is the right pattern for surfacing Java exceptions that Python's Exception misses, but here no exception exists at either layer. Keep the pattern for other system.db calls; do not rely on it for this one.
• Clearing a non-cached query proves nothing. If caching is off, the query always hits the database and the clear has no observable effect. The registry excludes these queries so a clear call against one is rejected rather than mistaken for success.

Commissioning Verification: Stale-Data Test

The wrapper proves a path is in the registry. Only a functional test proves the path evicts the cache. Run this once per cached query at commissioning and again after any rename, move, or project copy.

1. Confirm caching is active on the target query in the Designer and note its cache duration. The test must finish well inside that window, or natural expiry will mask a failed clear.
2. Run the query with a fixed parameter set using system.db.runNamedQuery from the Script Console or a test view. Record the returned value for one specific row.
3. Change that row directly in the database using a database tool or a test table, not through the named query.
4. Rerun the query with the identical parameter set. Expect the old value. If the new value appears, caching is not active for that parameter set; fix the query settings before continuing.
5. Call nqcache.clear() with the query's path. Confirm the NQCache log entry appears in the gateway logs.
6. Rerun the query with the identical parameter set. Expect the new value. If the old value persists, the registry path does not match the query or the call targeted the wrong project; correct the path and repeat from step 3.
7. Run the negative test. Call the wrapper with a nonsense path and confirm it raises ValueError. Then call the raw system.db.clearNamedQueryCache with the same nonsense path and confirm it still returns None without raising. If the raw call now raises, the platform behavior has changed after an upgrade; review every handler around cache clears before signing off.

FAQ