Difference between revisions of "Query Mode"

From BaseX Documentation
Jump to navigation Jump to search
 
(46 intermediate revisions by 4 users not shown)
Line 1: Line 1:
<p>In the query mode a query can be send to the server and executed
+
<p>The query mode of the [[Clients]] allows you to bind external variables to a query
in an iterative manner. For this you have 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 an forward-only iterator to get each result of the query.
 
Furthermore it is possible to bind variables to the query using the <code>bind()</code> function
 
of the query object.</p>  
 
 
   
 
   
<h2>Usage</h2>
+
==Usage==
 
   
 
   
<p>The query execution works as follows:</p>
+
The query execution works as follows:
 
   
 
   
<ol start="1">
+
# Create a new session instance with hostname, port, username and password.
<li>Create a new session instance with hostname, port, username and password.</li>
+
# Call <code>query()</code> with your XQuery expression to get a query object.
<li>Call the <code>query()</code> function of the session with the query as argument to get your query object.</li>
+
# Optionally bind variables to the query with one of the <code>bind()</code> functions.
<li>Optionally bind variables to the query with the <code>bind()</code> function.</li>
+
# Optionally bind a value to the context item via <code>context()</code>.
<li>Initialize query output via <code>init()</code>.</li>
+
# Iterate through the query object with the <code>more()</code> and <code>next()</code> functions.
<li>Iterate through the query object with the <code>more()</code> and <code>next()</code> functions.
+
# As an alternative, call <code>execute()</code> to get the whole result at a time.
If an error occurs, an exception is thrown.</li>  
+
# <code>info()</code> gives you information on query evaluation.
<li>Close the query with <code>close()</code>.</li>  
+
# <code>options()</code> returns the query serialization parameters.
</ol>
+
# Don't forget to close the query with <code>close()</code>.
   
+
 
<h2>Example</h2>
+
==PHP Example==
   
+
 
<ol start="1">
+
Taken from our [https://github.com/BaseXdb/basex/blob/master/basex-api/src/main/php/QueryBindExample.php repository]:
<li>Create a session object: <code>Session session = new Session("localhost", 1984, "admin", "admin");</code></li>
+
 
<li>Define a query and create a query object:<br/>
+
<syntaxhighlight lang="php">
     <code>String q = "declare variable $name external; " +
+
<?php
          "for $i in 1 to 10 return element { $name } { $i }";
+
/*
Query query = session.query(q);</code></li>
+
  * This example shows how queries can be executed in an iterative manner.
<li>Call the bind method of your query object:<br/>
+
* Documentation: http://basex.org/api
     <code>query.bind("$name", "Number");</code></li>
+
*
<li>Call the init method of your query object:<br/>
+
* (C) BaseX Team 2005-15, BSD License
     <code>print query.init();</code></li>
+
  */
<li>Iterate through the query object:<br/>
+
include("BaseXClient.php");
     <code>while(query.more()) print query.next();</code></li>  
+
 
<li>Close your query object:<br/>
+
try {
    <code>print query.close();</code></li>  
+
  // create session
</ol>
+
  $session = new Session("localhost", 1984, "admin", "...");
[[Category:Wikify]]
+
 
 +
  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: {{Code|context()}} function

Latest revision as of 14:43, 25 July 2022

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[edit]

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[edit]

Taken from our repository:

<?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", "...");
  
  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();
}
?>

Changelog[edit]

Version 7.2
  • Added: context() function