diff --git a/docs/index.rst b/docs/index.rst index 774f55e..145dadd 100755 --- a/docs/index.rst +++ b/docs/index.rst @@ -69,6 +69,7 @@ Contents install tutorial + query API Documentation Development diff --git a/docs/query.rst b/docs/query.rst new file mode 100644 index 0000000..7acd060 --- /dev/null +++ b/docs/query.rst @@ -0,0 +1,153 @@ +The django-find Query Language +============================== + +Introduction +------------ + +In this chapter, we explain the query language that can be passed to +``Searchable.by_query()``. + +For example: + +- ``hello world`` (searches all fields for hello and world) +- ``robert OR title:road`` (searches all fields for "robert", and "title" for "road") + +The basics +---------- + +To search all available fields, simply enter a word. For example, +the following query searches all fields for "test":: + + test + +When using multiple words, the query returns all entries that match +all of the words. In other words, the following query returns all +entries that have both, 'foo' in any field AND 'bar' in any field:: + + foo bar + +To search for strings including whitespace, use double quotes. The +following string returns all models that have a field containing +"foo bar" (without quotes):: + + "foo bar" + +Limiting a search to the beginning or end of a string +----------------------------------------------------- + +To search a string in a particular location of a field, use the +``^`` and ``$`` operators. The search at the beginning, use:: + + ^test + author:^robert + +To search a string at the end of a field, use:: + + test$ + author:frost$ + +To look for an exact match, use both:: + + ^test$ + author:^frost$ + author:"^robert frost$" + +Search individual model fields +------------------------------ + +To limit your search to a specific field of a model, you can +use the following syntax:: + + author:robert + author:"robert frost" + author:robert author:frost title:road + +Boolean operators +----------------- + +Boolean AND +~~~~~~~~~~~ + +When you specify multiple words, django-find by default returns +all entries that match all of the words. In other words, django-find +behaves like a boolean AND. The following queries are all equivalent:: + + foo bar + foo AND bar + foo and bar + "foo" and "bar" + +Boolean OR +~~~~~~~~~~ + +You can also use boolean OR operators. Here are some examples:: + + "robert frost" OR "mark twain" + robert or mark + ^robert or twain$ or foo or title:test + author:^robert or author:twain$ + +Boolean NOT +~~~~~~~~~~~ + +To find fields that DON'T match a particular string, use NOT:: + + "robert frost" not title:"the road" + "robert frost" and not title:"the road" + not foo or not bar + +Grouping +-------- + +For more complex searches, you can use brackets to group sub-expressions. +Arbitrary nesting is supported:: + + author:robert and not (title:"the road" or title:"yellow") + test (name:foo and (book:one or book:two) and (chapter:10 or chapter:12 or chapter:13)) + +Searching dates and times +------------------------- + +Date formats +~~~~~~~~~~~~ + +django-find accepts all formats that are supported by the +`dateparser `_ python module. +Some examples:: + + 12/12/12 + 2018-01-22 + "2018-01-22 10:00" + "10:40 pm" + "August 14, 2015 EST" + "1 min ago" + "2 weeks ago" + "3 months, 1 week and 1 day ago" + "in 2 days" + tomorrow + +For a full list of supported formats, please check the +`dateparser documentation `_. + +Searching for ranges +~~~~~~~~~~~~~~~~~~~~ + +When searching for dates and times, the ``^`` and ``$`` have special +meanings: You can use them to look for time ranges. The following query +returns all entries that were updated after the beginning of +January 1st, 12:00am:: + + updated:^2018-1-1 + +Similarly, you can get the entries that were updated before 2018:: + + updated:2018-1-1$ + +To look for a range, use AND:: + + updated:^2018-1-1 updated:2019-1-1$ + updated:^2018-1-1 AND updated:2019-1-1$ + +To look for an exact match, use both:: + + updated:"^2018-1-1 11:00$" diff --git a/docs/tutorial.rst b/docs/tutorial.rst index 818283f..7654b92 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -12,15 +12,12 @@ Motivation Assume you want to add a search box to your user interface, where your users can search your models using a simple query language. -django-find supports the following queries: +For example: - ``hello world`` (searches all fields for hello and world) -- ``author:robert OR title:road`` (searches the field "author" for "robert", and "title" for "road") -- ``author:"robert frost" and (title:road or chapter:2)`` (the AND is optional, it is implied by default) -- ``^robert`` (find anything that starts with "robert") -- ``robert$`` (find anything that ends with "robert") -- ``^robert$ and not title:road`` (find anything that equals "robert" and not the title "road") -- ``test (name:foo and (book:one or book:two) and (chapter:10 or chapter:12 or chapter:13))`` (arbitrary nesting is supported) +- ``robert OR title:road`` (searches all fields for "robert", and "title" for "road") + +The documentation of the query language is :doc:`here `. Alternatively, you may want to allow the user to specify the models and columns to display with a UI like this: