diff --git a/docs/index.rst b/docs/index.rst
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -26,6 +26,7 @@
    :caption: Contents:
 
    cli
+   query-language
 
 Reference Documentation
 -----------------------
diff --git a/docs/query-language.rst b/docs/query-language.rst
new file mode 100644
--- /dev/null
+++ b/docs/query-language.rst
@@ -0,0 +1,154 @@
+Search Query Language Syntax
+============================
+
+
+Every query is composed of filters separated by whitespaces.
+These filters have a 3 components in the order : ``Name Operator Value``
+
+**Note:** It's not necessary to put whitespace between these three components.
+The parser is intelligent enough to identify them even if the
+whitespaces are removed.
+
+The filters have been classfied on based on the type of the value that it expects.
+
+
+Pattern filters
+---------------
+
+    * Name: ``url`` ``metadata``
+    * Operator: ``:``
+    * Value: String wrapped in inverted commas(``"`` or ``'``)
+
+**Note:** If the string has no whitespace then the inverted comma becomes optional.
+
+**Examples:**
+
+    * ``url : https://github.com/Django/django``
+    * ``url : kubernetes``
+    * ``url : "github python"``
+    * ``metadata : orchestration``
+    * ``metadata : "javascript language"``
+
+Boolean filters
+---------------
+
+
+    * Name: ``with_visit``
+    * Operator: ``:``
+    * Value: ``true`` or ``false``
+
+**Examples:**
+
+    * ``with_visit : true``
+    * ``with_visit : false``
+
+
+Numeric filters
+---------------
+
+    * Name: ``nb_visits``
+    * Operator: ``<`` ``<=`` ``=`` ``!=`` ``>`` ``>=``
+    * Value: Positive integer
+
+**Examples:**
+
+
+    * ``nb_visits > 2``
+    * ``nb_visits = 5``
+    * ``nb_visits <= 10``
+
+
+Un-bounded List filters
+-----------------------
+
+    * Name: ``programming_languages`` ``licenses`` ``keywords``
+    * Operator: ``in`` ``not in``
+    * Value: Array of Strings (separated with ``,``)
+
+**Note:** If string has no whitespace then the inverted comma becomes optional.
+
+**Examples:**
+
+    * ``programming_languages in [python, js]``
+    * ``licenses in ["GPL 3.0 or later", MIT]``
+    * ``keywords in ["Software Heritage", swh]``
+
+
+Bounded List filters
+--------------------
+
+    visit_types
+    """""""""""
+
+    * Name: ``visit_types``
+    * Operator: ``:``
+    * Value: Array with elements
+
+        ``any``
+        ``cran``
+        ``deb``
+        ``deposit``
+        ``ftp``
+        ``hg``
+        ``git``
+        ``nixguix``
+        ``npm``
+        ``pypi``
+        ``svn``
+        ``tar``
+
+    * Name: ``sort_by``
+    * Operator: ``:``
+    * Value: Array with elements
+
+        ``nb_visits``
+        ``last_visit_date``
+        ``last_eventful_visit_date``
+        ``last_revision_date``
+        ``last_release_date``
+        ``date_created``
+        ``date_modified``
+        ``date_published``
+
+**Examples:**
+
+
+    * ``visit_types : [svn, npm]``
+    * ``visit_types : [nixguix, "ftp"]``
+    * ``sort_by : ["last_visit_date", date_created]``
+    * ``sort_by : [nb_visits, date_modified]``
+
+Date filters
+------------
+
+    * Name:
+
+            * ``last_visit_date``
+            * ``last_eventful_visit_date``
+            * ``last_revision_date``
+            * ``last_release_date``
+            * ``date_created``
+            * ``date_modified``
+            * ``date_published``
+
+    * Operator: ``<`` ``<=`` ``=`` ``!=`` ``>`` ``>=``
+    * Value: Date in ``YYYY-MM-DD`` or ``Standard ISO`` format
+
+**Examples:**
+
+    * ``last_visit_date > 2001-01-01 last_visit_date < 2001-01-01``
+    * ``last_revision_date = "2000-01-01 18:35Z"``
+    * ``last_release_date != "2021-07-17T18:35:00Z"``
+    * ``date_created <= "2021-07-17 18:35"``
+
+Limit filter
+------------
+
+    * Name: ``limit``
+    * Operator: ``=``
+    * Value: Positive Integer
+
+**Examples:**
+
+    * ``limit = 1``
+    * ``limit = 15``