[Jifty-commit] r5694 - Jifty-DBI/branches/tisql/doc/tisql

[Jifty commits]

Author: ruz
Date: Tue Aug 12 03:09:28 2008
New Revision: 5694

Added:
   Jifty-DBI/branches/tisql/doc/tisql/
   Jifty-DBI/branches/tisql/doc/tisql/basics.pod
   Jifty-DBI/branches/tisql/doc/tisql/joins_reusing.txt
   Jifty-DBI/branches/tisql/doc/tisql/old_doc.txt

Log:
* add some docs: new, old or any. everything else is pen writen
  in a notebook.

Added: Jifty-DBI/branches/tisql/doc/tisql/basics.pod
==============================================================================
--- (empty file)
+++ Jifty-DBI/branches/tisql/doc/tisql/basics.pod	Tue Aug 12 03:09:28 2008
@@ -0,0 +1,58 @@
+
+=head1 Basics of TISQL
+
+=head1 History
+
+It all comes from L<DBIx::SearchBuilder> and RT which has quite flexible
+query builder. Queries are implemented as strings close to SQL, but with
+special syntax for columns. For example it can be 'Requester.Login =
+"ruz"'. Such thing works quite good, but only for tickets and has some
+limitations, so I've decided to reimplement it in Jifty and improve.
+
+=head1 Basic syntax
+
+=head2 Boolean logic
+
+Everything is pretty simple here:
+
+=over 4
+
+=item boolean operator - 'AND' and 'OR'
+
+=item paranthesis - '(' and ')'
+
+=item boolean operands - our conditions
+
+=back
+
+So the following is our simple boolean expression:
+
+    ( <cond> OR <cond> ) AND <cond>
+
+In query language itself we'll have operators and operands too, we'll try
+to avoid cofusion by clarifing if it's boolean's or TISQL's. I'll use paren
+for paranthesis and open/close paren (/) respectively.
+
+See also L<Parse::BooleanLogic> for details on internals.
+
+=head2 Quoting
+
+As usually happens with strings we need some quoting. Almost all literal
+strings have to be quoted with " or ' and only quoting character inside
+have to be escaped with '\'. Some examples:
+
+    "a string"
+    "ruz's cool string"
+    'ruz\'s cool string'
+    'we can have "mixed" quoting'
+
+=head1 Conditions
+
+=head2 Basic syntax
+
+    <column> <uni_op> - .resolved IS NULL
+    <column> <bi_op> <constant> - ".id = 1" or ".created > '2008-03-25'"
+    <column> <bi_op> <column> - ".Member = u.id"
+
+=head2 Column syntax
+

Added: Jifty-DBI/branches/tisql/doc/tisql/joins_reusing.txt
==============================================================================
--- (empty file)
+++ Jifty-DBI/branches/tisql/doc/tisql/joins_reusing.txt	Tue Aug 12 03:09:28 2008
@@ -0,0 +1,34 @@
+Ok, we've figured out syntax, let's play with number of joins.
+
+'.tag.value = "zoo" OR .tag.value = "bar"'
+
+This is the simplest query when we can bundle conditions and use on
+join, but this rule applies only to OR binary operator, when AND
+operator with positive conditions requires at least two joins. In the
+case of AND you have to use different joins as the same record you
+join can not be 'foo' and 'bar' at the same time.
+
+'.tag.value != "zoo"'
+
+Do you remember I wrote about positive conditions is such queries. I
+was talking in such way because if we implement this condition in the
+same way as '.tag.value = "zoo"' then we'll get wrong results, we'll
+find all objects that have at least one tag that is not 'zoo' instead
+we have to use positive condition in a left join and check that the
+right part is empty. Something like:
+ SELECT o.* FROM o LEFT JOIN t ON t.object = o.id AND t.value = 'zoo'
+WHERE t.value IS NULL;
+Note that we invert operator, so query is more closer to "NOT
+(.tag.value = 'zoo')"
+
+'.tag.value != "zoo" AND .tag.value != "bar"'
+
+Smoothly we move to bundling negative conditions joined by AND binary
+operator. Using boolean logic we can rewrite the query into 'NOT(
+.tag.value = "zoo" OR .tag.value = "bar" )' and things are clearer
+now.
+
+What about more complex examples? I use Parse::BooleanLogic, then I've
+implemented filter that  leaves two conditions in the structure, so we
+can figure out relation between any pair of conditions in the query.
+

Added: Jifty-DBI/branches/tisql/doc/tisql/old_doc.txt
==============================================================================
--- (empty file)
+++ Jifty-DBI/branches/tisql/doc/tisql/old_doc.txt	Tue Aug 12 03:09:28 2008
@@ -0,0 +1,52 @@
+In my research I'm moving from TicketSQL to a new query language (call
+it "tisql" now, but that's a subject to change :). Let's define conditions
+people want to use during searches by tags and any other one-to-many
+relation:
+* has no any tag
+* has at least one tag
+* has tag X
+* has no tag Y
+To be more generic, let's change last two conditions to "has [no] tag
+that matches positive condition X". I'll describe later why condition
+should be positive.
+
+Here is syntax I suggest for these queries:
+* ".tag IS NULL"
+* ".tag IS NOT NULL"
+* ".tag.value = 'foo'"
+* ".tag.value != 'bar'"
+
+Formats of operators and values are well known, but I want to stop for
+while on a format of column, which is the following:
+keyword_definition: [ alias ] '.' <column_definition>
+column_definition: real_column | virtual_column [ '.' <column_definition> ]
+
+Alias is optional and describing it purposes is out of the scope of
+this chapter, default value is 'main' or the current collection. so
+$objects->JQL(".type = 'ticket'") select objects where type is ticket.
+"type" is a real column of the collection, when "tag" is a virtual and
+should be described in the model as well.
+
+".tag IS NULL" vs ".tag.value IS NULL"
+
+these are two different queries, where the first one selects objects
+without tags, but the latter one selects objects that has at least one
+associated tag record with column 'value' equal to NULL, for tags it's
+definitely strange query, however it can be useful, for example
+'.children.resolved_date IS NULL' which select some objects that have
+not resolved children.
+
+".tag = 'foo'"
+
+For now it's illegal query and you have to use ".tag.column = 'foo'"
+instead, but it would be cool to be able to define preferred real
+column per model, in the case this will be nice.
+
+Complex queries:
+* '(.tag.value = "foo" AND .type = "memo") OR (.tag.value = "bar" AND
+.type = "news")'
+** select all memos with tag foo or news with tag bar
+* '.tag.value = "zoo" OR (.tag.value = "foo" AND .tag.value = "bar")'
+** objects with tag zoo or tagged with foo and bar at the same time
+
+Ok, we've figured out syntax, let's play with number of joins.