view release on metacpan or  search on metacpan

doc/src/docsrc/250tql.xml  view on Meta::CPAN

		</para>

		<para>
		Now on to the queries.
		</para>

<!-- t/xTqlMt.t -->
<exdump>
> connect c1
c1|ready
> c1|d,symbol,OP_INSERT,ABC,ABC Corp,1.0
</exdump>

		<para>
		Starts a client connection and sends some data.
		</para>

<!-- t/xTqlMt.t -->
<exdump>
> c1|querysub,q1,query1,{read table symbol}{print tokenized 0}
c1|d,query1,OP_INSERT,ABC,ABC Corp,1
c1|querysub,q1,query1
</exdump>

		<para>
		The <quote>querysub</quote> command does the <quote>query-and-subscribe</quote>: reads the
		initial state of the table, processed through the query, and then
		subscribes to any future updates. The single-threaded variety of TQL
		doesn't do this, it does just the one-time queries. The multithreaded
		TQL could potentially do the one-time queries, and also just the subscribes
		without the initial state, but so far I've been cutting corners
		and the only thing that's actually available is the combination
		of two, the <quote>querysub</quote>.
		</para>

		<para>
		Similarly to the other commands, <quote>q1</quote> is the command identifier. The next
		field <quote>query1</quote> is the name for the query, it's the name that will be
		shown for the data lines coming out of the query. And then goes the
		query in the brace-quoted format, same as in the single-threaded TQL (and
		there is no further splitting by commas, so the commas can be used
		freely in the query).
		</para>

		<para>
		The identifier and the name of the query sound kind of redundant. But
		the client may generate them in different ways and need both. The name
		has the more symbolic character. The identifier can be generated as a
		sequence of numbers, so that the client can keep track of its progress
		more easily. And the error reports include the identifier but not the
		query name in them.
		</para>

		<para>
		For the query, there is no special line coming out before the initial
		dump. Supposedly, there would not be more than one query in flight with
		the same name, so they could be easily told apart based on the name in
		the data lines. There is also an underlying consideration that when the
		query involves a join, in the future the initial dump might be
		happening in multiple chunks, requiring to either surround every chunk
		with the start-end lines or just let them go without the extra
		notifications, as they are now.
		</para>
		 
		<para>
		And the initial dump ends as usual with getting the echo of the command
		(without the query part) back.
		</para>

		<para>
		This particular query is very simple and equivalent to a <quote>dumpsub</quote>.
		</para>

<!-- t/xTqlMt.t -->
<exdump>
> c1|d,symbol,OP_INSERT,DEF,Defense Corp,2.0
c1|d,query1,OP_INSERT,DEF,Defense Corp,2
</exdump>

		<para>
		Send more data and it will come out of the query.
		</para>

<!-- t/xTqlMt.t -->
<exdump>
> c1|querysub,q2,query2,{read table symbol}{where istrue {$%symbol =~ /^A/}}{project fields {symbol eps}}
c1|t,query2,query2 OP_INSERT symbol="ABC" eps="1"
c1|querysub,q2,query2
</exdump>

		<para>
		This query is more complicated, doing a selection (the <quote>where</quote> query
		command) and projection. It also prints the results in the tokenized
		format (the <quote>print</quote> command gets added automatically if it wasn't used
		explicitly, and the default options for it enable the tokenized
		format).
		</para>

		<para>
		The tokenized lines come out with the command <quote>t</quote>, query name and then
		the contents of the row. The query name happens to be sent twice, and
		I'm not sure yet if it's a feature or a bug.
		</para>

<!-- t/xTqlMt.t -->
<exdump>
> c1|d,symbol,OP_INSERT,AAA,Absolute Auto Analytics Inc,3.0
c1|d,query1,OP_INSERT,AAA,Absolute Auto Analytics Inc,3
c1|t,query2,query2 OP_INSERT symbol="AAA" eps="3"
> c1|d,symbol,OP_DELETE,DEF,Defense Corp,2.0
c1|d,query1,OP_DELETE,DEF,Defense Corp,2
</exdump>

		<para>
		More examples of the data sent, getting processed by both queries.  In
		the second case the <quote>where</quote> filters out the row from query2, so only
		query1 produces the result.
		</para>

<!-- t/xTqlMt.t -->
<exdump>