How to use unicode field names in jira IQL query?
- User
How to use unicode field names in jira IQL query?
Assistant
Of course! Using Unicode field names (attributes) in Jira IQL (Insight Query Language, now part of Assets in Jira Service Management) is a common requirement for international teams.
The key to making it work is simple: You must enclose the Unicode field name in double quotes (
").The IQL parser needs these quotes to understand that the entire string, including special characters, spaces, or non-ASCII characters, constitutes a single identifier (the name of your attribute or object type).
The Rule of Thumb
- For simple, single-word ASCII names: Quotes are optional (e.g.,
Status,Hostname). - For names with spaces, special characters, or Unicode characters: Quotes are mandatory (e.g.,
"Número de Série","Статус","Ubicación").
Let's break it down with examples.
How to Use Unicode Field Names in IQL
Step 1: Identify the Exact Field Name
First, ensure you have the exact name of the attribute as it appears in your Assets schema configuration. Typos are the most common source of errors. For example, is it "Ubicación" or "Ubicacion"? The accent matters.
Step 2: Enclose the Name in Double Quotes
Wrap the exact field name in double quotes (
"FieldName") within your query.Step 3: Write Your Query
Combine it with the rest of your IQL query.
Examples
Let's assume you have an object schema called "IT Assets" with an object type called "Laptops".
Example 1: Field with Accented Characters (Spanish)
You have an attribute named "Ubicación" (Location) and you want to find all laptops in Madrid.
-
Incorrect (will fail):
objectType = Laptops AND Ubicación = "Madrid"Why it fails: The IQL parser will see
Ubicaciónas an unknown keyword because of theócharacter and the lack of quotes. -
Correct:
objectType = Laptops AND "Ubicación" = "Madrid"Why it works:
"Ubicación"tells the parser to treat the entire string as the attribute name.
Example 2: Field in a Non-Latin Script (Cyrillic/Russian)
You have an attribute named "Статус" (Status) and you want to find all assets that are "In use".
-
Incorrect (will fail):
Статус = "In use" -
Correct:
"Статус" = "In use"
Example 3: Field with Spaces and Unicode (Portuguese/Spanish)
You have an attribute named "Número de Série" (Serial Number).
-
Incorrect (will fail):
Número de Série = "ABC-12345"Why it fails: The parser gets confused by the spaces and the
úcharacter. -
Correct:
"Número de Série" = "ABC-12345"
Example 4: Querying for an Object Type with a Unicode Name
The same rule applies to object type names. If your object type is called "Компьютеры" (Computers).
- Correct:
objectType = "Компьютеры"
Common Pitfalls and Troubleshooting
-
Single Quotes vs. Double Quotes: This is the most common mistake.
- Double Quotes (
") are for identifiers: object type names and attribute names. ("Ubicación") - Single Quotes (
') are for string values in your query. ('Madrid'). Note: In many JIRA contexts, double quotes also work for values, but the standard practice is to use single quotes for values to avoid confusion. - Example showing both:
objectType = "Компьютеры" AND "Статус" = 'Активный'
- Double Quotes (
-
Typos or Mismatches: Double-check the attribute name in your object schema configuration. Go to Project Settings > Assets > Object Schemas, select your schema, and inspect the attributes of the relevant object type. Copy and paste the name from there if you are unsure.
-
Invisible Characters: If you copy-paste the name from a webpage or a document, you might accidentally include non-printing characters. If your query fails, try re-typing the name manually inside the double quotes.
Best Practice
Even if your custom field name is simple ASCII but contains spaces (e.g., "Serial Number"), you must use double quotes.
To avoid confusion and prevent future errors, it's a good habit to always enclose your custom attribute and object type names in double quotes, regardless of whether they contain Unicode characters or spaces.
// Good, but brittle if the name changes to "Host Name" Hostname = "server-01.company.local" // Better, always works "Hostname" = "server-01.company.local"By following this simple rule of using double quotes, you can reliably query your Assets data using any language or character set.
- For simple, single-word ASCII names: Quotes are optional (e.g.,
- User
how to write case insensitive query to match substring in jira IQL?
Assistant
Excellent question! This is a very common requirement in IQL.
To write a case-insensitive query that matches a substring, you have two primary, easy-to-use operators. The simplest and most direct is the
~(CONTAINS) operator.1. The Best Method: Use the
~(CONTAINS) OperatorThe
~operator is specifically designed for this purpose. It checks if a field's value contains a given substring, and it is case-insensitive by default.Syntax:
"Attribute Name" ~ "substring"Example:
Let's say you want to find all "Laptop" objects where the "Model" attribute contains the string "pro", regardless of case (e.g., "MacBook Pro", "probook", "Spectre PRO").
Your IQL query would be:
objectType = "Laptops" AND "Model" ~ "pro"This single query will successfully match all of the following values for the "Model" attribute:
MacBook ProHP ProBookThinkPad T14s ProfessionalPRO-X1
2. The Alternative Method: Use the
LIKEOperatorIf you are more familiar with SQL, you might reach for the
LIKEoperator. In Jira IQL, theLIKEoperator is also case-insensitive by default. To make it match a substring, you must use the percent sign (%) as a wildcard character.%represents zero, one, or multiple characters.
Syntax for Substring Matching:
"Attribute Name" LIKE "%substring%"Example:
Using the same scenario as above, to find all laptops with "pro" in the model name, you would write:
objectType = "Laptops" AND "Model" LIKE "%pro%"This query achieves the exact same result as using the
~operator. It will find "MacBook Pro", "probook", etc.
Comparison:
~vs.LIKEOperator Name What It Does Example When to Use ~CONTAINS Case-insensitive substring search. Simple and direct. "Model" ~ "pro"This is the recommended method for this exact need. LIKELIKE Case-insensitive pattern matching with wildcards ( %,_)."Model" LIKE "%pro%"When you need more complex pattern matching. !~NOT CONTAINS Finds objects that do not contain the case-insensitive substring. "Model" !~ "pro"For negative substring searches. NOT LIKENOT LIKE Finds objects that do not match the case-insensitive pattern. "Model" NOT LIKE "%pro%"For negative pattern matching. Key takeaway: For a simple "contains" search,
~is cleaner and more readable. For more advanced patterns,LIKEis more flexible.Advanced
LIKEPatterns (For Your Information)The
LIKEoperator is more powerful if your needs are more specific:- Starts with: Find models starting with "Mac".
"Model" LIKE "Mac%" - Ends with: Find models ending with "Pro".
"Model" LIKE "%Pro" - Specific character wildcard (
_): Find models like "Pro X1", "Pro Y1", where_matches a single character."Model" LIKE "Pro _1"
Putting It All Together: A Complete Example
Let's combine this with the previous topic of Unicode field names.
Scenario: You have an object type "Dispositivos" (Devices). It has a Unicode attribute named "Número de Série" (Serial Number). You want to find all devices where the serial number contains the substring "axb", but you don't know the casing.
Correct IQL Query:
objectType = "Dispositivos" AND "Número de Série" ~ "axb"This query would correctly match serial numbers like:
SN-123-AXB-456sn-axb-999789aXb001
By using the
~operator and correctly quoting your Unicode field name, you can build powerful, flexible, and internationally-friendly IQL queries.- User
Why i get error with tilda in IQL like this "IQL has invalid syntax at position with error message no viable alternative at input ~"?
Assistant
That is a very specific and excellent question. The error message
"IQL has invalid syntax at position with error message no viable alternative at input ~"is highly informative.It tells you that the IQL parser successfully read your query up to the tilde (
~) character, but at that exact point, it did not expect to see a~. Based on the rules it knows, a~is not a "viable alternative" for what should come next.This error almost always happens for one primary reason:
You are trying to use the
~(CONTAINS) operator on an attribute that is not a plain text field.The
~operator is designed exclusively for searching within text-based attributes. If you use it on other attribute types, the IQL parser will reject it.
The Most Common Causes and Their Solutions
Let's break down the types of attributes where this error occurs and how to fix your query for each one.
1. Attribute is an Object Reference
This is the most common culprit. You have an attribute like "Owner," "Location," or "Host," which doesn't store text but links to another object. You cannot use
~directly on the object itself.-
Incorrect Query (Causes the Error):
objectType = "Laptops" AND "Owner" ~ "Smith"Why it fails: "Owner" is an object, not a string. The query doesn't know which attribute of the Owner object to search.
-
Correct Solution (Use Dot Notation): You must use dot notation to specify a text attribute of the referenced object.
// Search the Owner's Name attribute objectType = "Laptops" AND "Owner".Name ~ "Smith" // Search the Owner's Email attribute objectType = "Laptops" AND "Owner".Email ~ "smith.j"
2. Attribute is a Status, Select, or Multi-Select List
These attributes are also treated as objects or special types, not plain text. You must use
INor=with the exact option name.-
Incorrect Query (Causes the Error):
"Status" ~ "In Prog" -
Correct Solution (Use
INor=):// Use = for an exact match "Status" = "In Progress" // Use IN to match multiple possible statuses "Status" IN ("In Progress", "Pending")
3. Attribute is a User
Similar to an object reference, a User attribute is a link to a user object.
-
Incorrect Query (Causes the Error):
"Assignee" ~ "John" -
Correct Solution (Use Dot Notation for User Properties): You can query against the user's
name(username/ID),displayName, oremailAddress.// Search by username "Assignee".name ~ "jsmith" // Search by full display name "Assignee".displayName ~ "John"
4. Attribute is a Number, Date, or Boolean
The
~operator is meaningless for these types.-
Incorrect:
"RAM (GB)" ~ "16" -
Correct:
"RAM (GB)" = 16(without quotes for the number) -
Incorrect:
"Warranty End" ~ "2024" -
Correct:
"Warranty End" > "2024-01-01"
How to Troubleshoot This Error
Follow these steps to quickly identify and fix the problem:
-
Identify the Attribute: Look at the attribute in your query that comes just before the
~. In"Owner" ~ "Smith", the attribute is"Owner". -
Check its Type:
- Go to your Jira Project Settings.
- Navigate to Assets -> Object Schemas.
- Select the correct schema and then the object type you are querying (e.g., "Laptops").
- Find the attribute in the list and look at its "Type" column.
-
Apply the Correct Syntax:
- If the type is Text, Textarea, or URL, the
~operator should work. If it doesn't, it could be a rare bug or a syntax error elsewhere in your query. - If the type is Object, User, Status, Select, Date, Number, etc., you are using the wrong operator. Refer to the solutions above and change your query accordingly.
- If the type is Text, Textarea, or URL, the
Summary Example
Scenario: You want to find all servers located in a data center with "ash" in its name (e.g., "Ashburn-DC-01"). The "Location" attribute on a Server object links to a Location object.
The Wrong Way (Generates the
~error):objectType = "Servers" AND "Location" ~ "ash"The Right Way (Using dot notation on the Location's
Nameattribute):objectType = "Servers" AND "Location".Name ~ "ash"-
Other models, same or similar prompt
Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.