I have a question regarding the text query parameter used in a GET request to /inventory/managedObjects. I am trying to fetch a device by its name. My initial approach was to use the text parameter, so I tried the following request:
/inventory/managedObjects?text=SITE_I/930
However, the result included not only the expected device, but also another device with name “SITE_I/729”. I checked the full response payload and that additional device doesn’t have any property whose name or value equals “SITE_I/930”.
The Core API documentation says:
Search for managed objects where a property value is equal to the given one. The following properties are examined: id, type, name, owner, externalIds.
Given this, I would expect only the device named “SITE_I/930” to be returned.
I’m using query param instead now, but I’d still like to understand the behavior of text.
In short, the text query parameter in the /inventory/managedObjects REST API call does a full-word search in those listed fields…however what this means is that the search term is broken up into words, and the query results will be returned when ANY of the words from the original search text are found.
In your example, you’re searching for “SITE_I/930”, so the database query will search for two words, “SITE_I” and “930” (due to the / character is classed as word separator), though only one search term has to match for the inventory managed object to match the criteria.
I couldn’t find the official documentation which mentions this, but it is definitely a commonly asked question as the results are unexpected for a lot of users. I’m not 100% sure on all of the word separators, but - is definitely one, but _ is not.
But as you mentioned, the inventory managed object Query Langauge is the better option in your case. The text (full word) search can be useful if you don’t know exactly what you’re looking for but you know a word, and want to find any inventory using that word.
I just want to add that this behavior is really unintuitive and directly contradicts the docs. The spec explicitly says it searches for objects “where a property value is equal to the given one”. An implicit, tokenized OR search is definitely not an exact match
This actually caught us off guard recently. We used the text parameter in a script, expecting an exact match. Because of this hidden word splitting, it matched a ton of unintended objects and we accidentally deleted them all. Luckily it was only in our dev environment, but it was a close call.
Is there any way to get the official docs updated to reflect how this actually works? Adding a quick note about the tokenization and OR logic would clear up a lot of confusion and save other teams from potential data loss.
