Difference between revisions of "Query Mode"

From BaseX Documentation
Jump to navigation Jump to search
(22 intermediate revisions by 3 users not shown)
Line 1: Line 1:
<p>In the query mode of the [[Language Bindings|bindings]], a query can be sent to the server and
+
<p>The query mode of the [[Clients]] allows you to bind external variables to a query
executed in an iterative manner. For this, you need to call the <code>query()</code> function
+
and evaluate the query in an iterative manner. The <code>query()</code> function of the
of the <code>Session</code> with your defined query. This will return a query object,
+
<code>Session</code> instance returns a new query instance.</p>
which comes with a forward-only iterator to get each result of the query.
 
Furthermore, variables can be bound to the query using the <code>bind()</code> function
 
of the query object.</p>  
 
 
   
 
   
 
==Usage==  
 
==Usage==  
 
   
 
   
<p>The query execution works as follows:</p>
+
The query execution works as follows:
 
   
 
   
#Create a new session instance with hostname, port, username and password.
+
# Create a new session instance with hostname, port, username and password.
#Call the <code>query()</code> function of the session with the query as argument to get your query object.
+
# Call <code>query()</code> with your XQuery expression to get a query object.
#Optionally bind variables to the query with the <code>bind()</code> function.
+
# Optionally bind variables to the query with one of the <code>bind()</code> functions.
#Initialize query output via <code>init()</code>.
+
# Optionally bind a value to the context item via <code>context()</code>.
#Iterate through the query object with the <code>more()</code> and <code>next()</code> functions. If an error occurs, an exception is thrown.
+
# Iterate through the query object with the <code>more()</code> and <code>next()</code> functions.
#Close the query with <code>close()</code>.
+
# As an alternative, call <code>execute()</code> to get the whole result at a time.
 +
# <code>info()</code> gives you information on query evaluation.
 +
# <code>options()</code> returns the query serialization parameters.
 +
# Don't forget to close the query with <code>close()</code>.
  
==Example in [https://svn.uni-konstanz.de/dbis/basex/trunk/api/etc/php/ PHP]==  
+
==PHP Example==
  
<pre class="brush:php">
+
Taken from our [https://github.com/BaseXdb/basex-api/blob/master/src/main/php/QueryBindExample.php repository]:
 +
 
 +
<syntaxhighlight lang="php">
 
<?php
 
<?php
 
/*
 
/*
Line 25: Line 27:
 
  * Documentation: http://basex.org/api
 
  * Documentation: http://basex.org/api
 
  *
 
  *
  * (C) BaseX Team 2005-11, ISC License
+
  * (C) BaseX Team 2005-15, BSD License
 
  */
 
  */
 
include("BaseXClient.php");
 
include("BaseXClient.php");
Line 42: Line 44:
 
     $query->bind("$name", "number");
 
     $query->bind("$name", "number");
  
     // initialize query
+
     // print result
    print $query->init();
+
     print $query->execute()."\n";
 
 
    // loop through all results
 
     while($query->more()) {
 
      print $query->next()."\n";
 
    }
 
  
 
     // close query instance
 
     // close query instance
     print $query->close();
+
     $query->close();
  
 
   } catch (Exception $e) {
 
   } catch (Exception $e) {
Line 66: Line 63:
 
}
 
}
 
?>
 
?>
</pre>
+
</syntaxhighlight>
 +
 
 +
=Changelog=
 +
 
 +
;Version 7.2
  
for more examples see the [[Languages|languages]] section.
+
* Added: {{Code|context()}} function
[[Category:Developer]]
 
[[Category:Server]]
 
[[Category:Language Bindings]]
 

Revision as of 13:20, 27 February 2020

The query mode of the Clients allows you to bind external variables to a query and evaluate the query in an iterative manner. The query() function of the Session instance returns a new query instance.

Usage

The query execution works as follows:

  1. Create a new session instance with hostname, port, username and password.
  2. Call query() with your XQuery expression to get a query object.
  3. Optionally bind variables to the query with one of the bind() functions.
  4. Optionally bind a value to the context item via context().
  5. Iterate through the query object with the more() and next() functions.
  6. As an alternative, call execute() to get the whole result at a time.
  7. info() gives you information on query evaluation.
  8. options() returns the query serialization parameters.
  9. Don't forget to close the query with close().

PHP Example

Taken from our repository:

<syntaxhighlight lang="php"> <?php /*

* This example shows how queries can be executed in an iterative manner.
* Documentation: http://basex.org/api
*
* (C) BaseX Team 2005-15, BSD License
*/

include("BaseXClient.php");

try {

 // create session
 $session = new Session("localhost", 1984, "admin", "admin");
 
 try {
   // create query instance
   $input = 'declare variable $name external; '.
     'for $i in 1 to 10 return element { $name } { $i }';
   $query = $session->query($input);
   // bind variable
   $query->bind("$name", "number");
   // print result
   print $query->execute()."\n";
   // close query instance
   $query->close();
 } catch (Exception $e) {
   // print exception
   print $e->getMessage();
 }
 // close session
 $session->close();

} catch (Exception $e) {

 // print exception
 print $e->getMessage();

} ?> </syntaxhighlight>

Changelog

Version 7.2
  • Added: context() function