[Jifty-commit] r5721 - Jifty-DBI/branches/tisql/doc/tisql
jifty-commit at lists.jifty.org
Thu Aug 14 20:23:12 EDT 2008
Date: Thu Aug 14 20:23:11 2008
New Revision: 5721
* update tisql documentation with examples
--- Jifty-DBI/branches/tisql/doc/tisql/basics.pod (original)
+++ Jifty-DBI/branches/tisql/doc/tisql/basics.pod Thu Aug 14 20:23:11 2008
@@ -1,6 +1,4 @@
-=head1 Basics of TISQL
It all comes from L<DBIx::SearchBuilder> and RT which has quite flexible
@@ -9,6 +7,19 @@
"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.
+Here is simple example:
+ my $articles = new MyApp::ArticleCollection;
+ ".author.name = 'ruz'"
+ ." AND .status = 'published'"
+ ." AND .tags.value = 'tisql'"
+Nice, isn't it? Yep, we think so too.
=head1 Basic syntax
=head2 Boolean logic
@@ -27,7 +38,7 @@
So the following is our simple boolean expression:
- ( <cond> OR <cond> ) AND <cond>
+ ( <a condition> OR <condition> ) AND <condition>
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
@@ -50,9 +61,124 @@
=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"
+ .resolved IS NULL
+ .id = 1
+ .created > '2008-03-25'
+ .subject like 'Re: %'
+So each condition is an operator, a column on its left side and constant or
+another column on the right. Operators like IS NULL has nothing on right side.
+=head2 Simple operators
+=item =, != - equality
+=item IS NULL, IS NOT NULL - tests for NULLs
+=item <, >, <=, >= - ranges
+=item LIKE, NOT LIKE - string pattern matching
+So everything is simple as in SQL.
=head2 Column syntax
+ [<alias>] ( '.' <column> )*
+Alias is optional and most of the time you don't need them, however them
+are desperatedly required in some situations, read about that below XXX
+link goes here. Let's leave them alone.
+When you apply a tisql query you do it on a collection of records, for
+example C<MyApp::Model::UserCollection>. Records in this collection have
+columns described by schema of the model C<MyApp::Model::User>. You skip
+alias to say that you want column of records in base collection, each
+column is prefixed with literal dot character, for example:
+JDBI supports referes_to definition for columns to delare named references
+to other records and collections. In tisql you can use this advantage and
+continue columns sequence to build conditions based on properties of
+related objects, for example:
+ # where member_of refers to groups collection, each group has name
+ # column
+ # where owner_of referes to tasks collection and tasks have tags
+Summary: an optional alias followed by one or more dot column pairs.
+=head2 Conditions on related records
+What do you expect to find when you write the following query:
+ .tags.value != 'X'
+Most people want to find all records without tag 'X', records without
+tags or records that has no tag 'X'. We're not exceptional to this desire.
+So not equal and negative pattern matching operators on long column sequences
+will as 'find records which have no related objects with properties equal
+or matching a value/pattern'.
+ .member_of.name != 'sales department'
+ .depends_on.status != 'done'
+Note that 'IS NOT NULL' operator is not affected. This can be changed as
+it's not clear what is better.
+=head2 Extended conditions on related records.
+As we figured out earlier each record in the collection you're limiting can
+be related to multiple sets of records. In such situation conditions
+described above are too limitted in many situations. Tisql provide 'has'
+and 'has no' conditions modifiers.
+=item C<has .reference.property = 'x'> - the same as C<.column.property =
+=item C<has no .reference.property = 'x'> - the same as C<.column.property
+=item C<has .reference.property != 'x'> - find records which refers to at
+least one record with property != 'x', for example C<has
+.sub_projects.status != 'done'> which find projects that have at least one
+not finished sub project.
+=item C<has no .reference.property != 'x'> - find records which has no
+refererences to records with property != 'x', for example C<has no
+.sub_projects.status != 'done'> which finds projects that either have no
+sub projects or all sub projects are done.
+=item C<has .reference> - the same as C<.reference.id IS NOT NULL>
+=item C<has no .reference> - the same as C<.reference.id IS NULL>
+=head2 Where are joins?
+=head2 Extended refers_to column declarations
+=head2 Adding new columns at run-time
More information about the Jifty-commit