From 6eaca162309ffaaeb5381404d4d6cb647dd3d350 Mon Sep 17 00:00:00 2001 From: Pavel Czerny Date: Wed, 13 Nov 2024 12:10:58 +0100 Subject: [PATCH] M #-: Update VM search with special characters (cherry picked from commit 1136eb935aab28f8871ca97c5e2eac2f35eef267) --- .../vm_management/vm_instances.rst | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/source/management_and_operations/vm_management/vm_instances.rst b/source/management_and_operations/vm_management/vm_instances.rst index 5190f84b9..d018f8745 100644 --- a/source/management_and_operations/vm_management/vm_instances.rst +++ b/source/management_and_operations/vm_management/vm_instances.rst @@ -157,10 +157,21 @@ and details about it can be obtained with ``show``: Searching for VM Instances -------------------------------------------------------------------------------- -You can search for VM instances by using the ``--search`` option of the ``onevm list`` command. This is specially useful on large environments with many VMs. The filter must be in a ``VM.KEY1=VALUE1&VM.KEY2=VALUE2`` format and will return all the VMs which fit the filter. The ``&`` works as logical AND. You can use ``*=VALUE`` to search the full VM body. +You can search for VM instances by using the ``--search`` option of the ``onevm list`` command. This is specially useful on large environments with many VMs. The filter must be in a ``VM.KEY1=VALUE1&VM.KEY2=VALUE2`` format and will return all the VMs which fit the filter. The ``&`` works as logical AND. You can use ``*=VALUE`` to search the full VM body or ``VM.TEMPLATE=VALUE`` to search whole template. Searching is performed using JSON on the whole body of the VM. You can use the MySQL JSON path without the leading ``$.``, information about the path structure can be found in the [MySQL Documentation](https://dev.mysql.com/doc/refman/5.7/en/json.html#json-path-syntax) or [MariaDB Documentation](https://mariadb.com/kb/en/jsonpath-expressions/). Currently, the value is wrapped in ``%`` for the query, so it will match if it contains the value provided. +The ``VALUE`` part of a search query can utilize special characters to create flexible matching patterns: + +* ``%``: Matches any string, allowing for wildcard searches. For example, ``a%a%a`` matches names containing three "a"s in any position, with any number of characters between them. +* ``_``: Matches any single character, enabling precise pattern matching. For instance, ``a_a_a`` matches names with three "a"s, each separated by exactly one character. +* ``&``: Cannot be used in the ``VALUE`` part of the search query, as it is always interpreted as logical AND operator and does not support escaping. + +To search for strings that contain ``%`` or ``_`` literally, escape these characters with a backslash ``\``. For example: + +* ``a\%a`` will search for "a%a" as an exact sequence. +* ``a\_a`` will match "a_a" without interpreting ``_`` as a single-character wildcard. + For example, for searching a VM with a specific MAC address: .. prompt:: text $ auto