.. _search-syntax:

Search syntax
***************

TreeSize provides a syntax that allows you to quickly and flexibly customize your search.

Examples for a simple search
===============================

Search for photos from 2022: ``Images 2022``

TreeSize will then list all image files, whether jpg, png, bmp or similar, with the modification date in 2022.

Search for large Office files: ``Office > 10MB``

TreeSize lists all Excel, Word, PDF, etc. files that are larger than 10 megabytes.

Search syntax structure
=========================

Certain keywords also offer the opportunity to formulate the search more precisely.

In addition to ``file names``, you can also search for ``file extensions``, ``size``, ``date``, ``file contents`` and much more.

Search terms can be combined via ``AND`` or ``OR`` and file names can be excluded from the search using the syntax.

It is also possible to use wildcards and regular expressions.

Below you will find a description of the permitted keywords and some use cases. For most keywords, there is a abbreviated form for faster search entry.

The search syntax is structured as follows:

.. code:: 
    
    <Property> <Operator> <Value>

For example:

.. code:: 
    
    name: = readme

This syntax finds all files that name (property) matches (operator) the word readme (value).

Several search terms can be combined:

.. code::

    name:=readme, name:=movie

Or

.. code::
    
    name:=readme OR name:=movie

Finds all files with 'readme' OR 'movie' in their name.

All properties, operators and conjunctions
============================================

The following table shows all available properties, operators and conjunctions that you can use in TreeSize.

.. note::
    
    When searching for file names, name: can be omitted. Regardless of this, the ``=`` character can generally be omitted as an operator, as well as ``AND`` as conjunction between two search terms.
    
    These are the default property, operator, and connection values used in the search. There are different spellings for individual properties, which can be found in the table below.

.. note::
    
    If you want to use reserved characters of the search syntax such as brackets, commas or spaces in the search term, the search term must be enclosed in double quotes. Examples are in the table below.

.. note::
    
    A note regarding dates: When using a date as part of the search term, the required date format depends on the region settings that are configured within Windows.


Properties
~~~~~~~~~~~~~~

.. list-table::
   :widths: 10 40 10 20 20
   :header-rows: 1

   * - Property
     - Description
     - Example
     - Alternative form
     - Explanation
   * - ``name:``
     - Search by file name. This is the default property that is used when no property is explicitly specified.
     - ``readme``
     - ``name:readme``
     - Search for all files whose file name contains the word 'readme'.
   * - ``path:``
     - Search by folder path.
     - ``path:Windows``
     - none
     - Search for all files and folders in the Windows folder.
   * - ``extension:``
     - Search by file extension.
     - ``ext:txt``
     - ``extension:txt``
     - Search for all files with the file extension 'txt'.
   * - ``group:``
     - Search by file group.
     - ``group:Video files``
     - none
     - Search for all video files. Information: The available file groups can be adjusted under 'Options > Configure file groups'.
   * - ``content:``
     - Search by file content.
     - ``cont:license``
     - ``content:license``
     - Full text search for all files whose file content contains the word 'license'.
   * - ``size:``
     - Search by file size.
     - ``size:<500MB``
     - none
     - Search all files smaller than 500 MB. Information: Folder sizes are not considered.
   * - ``accessed:``
     - Search by access date.
     - ``accessed:<=01.11.2021``
     - none
     - Search for files with access date in the specified time interval.
   * - ``created:``
     - Search by creation date.
     - ``created:<=01.11.2021``
     - none
     - Search for files with creation date in the specified time interval.
   * - ``modified:``
     - Search by modification date.
     - ``modified:<=01.11.2021``
     - none
     - Search for files with modification date in the specified time interval.
   * - ``datetaken:``
     - Search by date taken (e.g., photos).
     - ``datetaken:03.03.2023``
     - none
     - Search for files taken on March 3, 2023.
   * - ``attribute:``
     - Search by file attributes.
     - ``attribute: HS``
     - none
     - Search for files with the file attributes H (Hidden) and S (System).
   * - ``keyword:``
     - Search by keywords in files.
     - ``keyword: my_keyword``
     - none
     - Search for files (e.g., docx files) marked with the keyword "my_keyword".
   * - ``owner:``
     - Search by file owner.
     - ``owner: John``
     - none
     - Search for files whose file owner is named "John".

Operators
~~~~~~~~~~~~~~

.. list-table::
   :widths: 10 40 10 20 20
   :header-rows: 1

   * - Operator
     - Description
     - Example
     - Alternative form
     - Explanation
   * - ``=``
     - The property must apply.
     - ``readme``
     - ``name:=readme``
     - Search for all files whose file name contains the word 'readme'. This is the default operator that is used if no operator is explicitly specified.
   * - ``!=``
     - The property must not apply.
     - ``!=readme``
     - ``name:!=readme``
     - Search for all files that do not contain the word 'readme'.
   * - ``~``
     - Can be used in conjunction with the `name:` property. The following value is a Regular Expression (Regex) and must apply to the property. Note: The :ref:`regular-expressions` must be enclosed in quotation marks if search syntax characters such as brackets, commas, or spaces are used.
     - ``~[0-9]``
     - ``name:~[0-9]``
     - Search for all files that have at least one digit in their name.
   * - ``!~``
     - Can be used in conjunction with the `name:` property. The following value is a Regular Expression (Regex) and must not apply to the property. Note: The :ref:`regular-expressions` must be enclosed in quotation marks if search syntax characters such as brackets, commas, or spaces are used.
     - ``!~[0-9]``
     - ``name:!~[0-9]``
     - Search for all files that have no digits in their names.
   * - ``> or >=``
     - Operator for size or date comparisons: The property must be greater than (or greater than or equal to) the specified value.
     - ``size:>= 5MB``
     - none
     - Search for all files that are bigger than or equal to 5 MB. Information: The search only refers to file sizes; folder sizes are not taken into account.
   * - ``< or <=``
     - Operator for size or date comparisons: The property must be smaller than (or smaller than or equal to) the specified value.
     - ``size:<= 500MB``
     - none
     - Search for all files that are less than or equal to 500 MB. Information: The search only refers to file sizes; folder sizes are not taken into account.
   * - ``( and )``
     - Parentheses can be used to group parts of the search input.
     - ``(readme, license)*.txt``
     - ``(name:=readme OR name:=license) AND *.txt``
     - Search for all text files that have the word "readme" or "license" in their filename.

Conjunctions
~~~~~~~~~~~~~~

.. list-table::
   :widths: 10 40 10 20 20
   :header-rows: 1

   * - Conjunction
     - Description
     - Example
     - Alternative form
     - Explanation
   * - ``Space character`` or ``AND``
     - The conjunct search patterns must all match.
     - ``readme ext:txt``
     - ``name:=readme AND extension:=txt``
     - Search for all files whose file name contains the word 'readme' and which have the file extension 'txt'. This is the default connection that is used if no connection is explicitly specified.
   * - ``Commar`` or ``OR``
     - At least one of the related search patterns must match.
     - ``readme, movie``
     - ``name:=readme OR name:=movie``
     - Search for all files whose file name contains the word 'readme' or 'movie'.

Reserved characters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When specifying values, more previsely the actual search pattern, there are various reserved characters such as wildcards or quotation marks for exact searches.

The following table lists these characters and explains them using some examples.

.. list-table::
   :widths: 10 40 10 20 20
   :header-rows: 1

   * - Example value
     - Description
     - Example
     - Alternative form
     - Results
   * - ``*readme*``
     - Search for readme, where any number of characters can be placed before and after the word. The word contains 'readme'.
     - ``*readme*``
     - ``name:=*readme*``
     - Finds: '123readme.txt', '123readme.docx' but NOT: 'read_me.txt', 'reading.docx'
   * - ``readme``
     - Corresponds *readme*. The two wildcards before and after the word can be omitted for simplicity.
     - ``readme``
     - ``name:=readme``
     - Finds: '123readme.txt', '123readme.docx' but NOT: 'read_me.txt', 'reading.docx'
   * - ``readme*``
     - Search for readme, where any number of characters can be placed after the word, but no characters are allowed before the word. The word begins with 'readme'.
     - ``readme*``
     - ``name:=readme*``
     - Finds: 'readme.txt', 'readme_c.docx' but NOT: '123readme.txt', 'read_me.txt'
   * - ``*readme``
     - Search for readme, where any number of characters can be placed before the word, but no characters are allowed after that. The word ends with 'readme'.
     - ``*readme``
     - ``name:=*readme``
     - Finds: '123readme', 'c_readme' but NOT: 'readme.txt', 'readme_c'
   * - ``"readme"``
     - Word search for the exact occurrence of the word "readme". It searches for the exact occurrence of the word without taking parts or variations of the word into account. This means that the searched word must be present in the text as an independent and complete word in order to be recognized as a hit.
     - ``"readme"``
     - ``name:="readme"``
     - Finds: 'readme' or 'readme.txt' but NOT: 'readmes.txt', '123readme'
   * - ``rea?me``
     - Search for file names beginning with 'rea' and ending with 'me' and containing exactly one character in between.
     - none
     - ``name:=rea?me``
     - Finds: 'readme', 'reasme', 'rea1me' but NOT: 'rea123me', 'readme.txt'
   * - ``\\*readme*``
     - Search for files that contain the term "readme" anywhere in their path.
     - ``\\*readme*``
     - ``name:=\\*readme*``
     - Finds: "readme.txt" in any folder, "abc.doc" in "C:\\temp\\readme\\local". but NOT: "abc.doc" in "C:\\temp\\local".
