Difference between revisions of "Query Mode"

From BaseX Documentation
Jump to navigation Jump to search
Line 12: Line 12:
 
# Call the <code>query()</code> function of the session with the query as argument to get your query object.
 
# Call the <code>query()</code> function of the session with the query as argument to get your query object.
 
# Optionally bind variables to the query with the <code>bind()</code> function.
 
# Optionally bind variables to the query with the <code>bind()</code> function.
# Initialize query output via <code>init()</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. If an error occurs, an exception is thrown.
 
# As an alternative, call <code>execute()</code> to get the whole result at a time. This will be faster in most cases, as the socket communication will be limited to a single call.
 
# As an alternative, call <code>execute()</code> to get the whole result at a time. This will be faster in most cases, as the socket communication will be limited to a single call.
# Optionally, call <code>info()</code> to get information on the number of results, query time, etc.
+
# <code>info()</code> gives you information on query evaluation.
 +
# <code>options()</code> returns the query serialization parameters.
 
# Close the query with <code>close()</code>.
 
# Close the query with <code>close()</code>.
  

Revision as of 13:42, 18 September 2011

The query mode of the Clients allows you to bind external variables to a query and evaluate the query in an iterative manner. For this, you need to call the query() function of the Session instance with your defined query. This will return a query object, which comes with a forward-only iterator. Variables can be bound to the query using the bind() function of the query object.

Usage

The query execution works as follows:

  1. Create a new session instance with hostname, port, username and password.
  2. Call the query() function of the session with the query as argument to get your query object.
  3. Optionally bind variables to the query with the bind() function.
  4. Iterate through the query object with the more() and next() functions. If an error occurs, an exception is thrown.
  5. As an alternative, call execute() to get the whole result at a time. This will be faster in most cases, as the socket communication will be limited to a single call.
  6. info() gives you information on query evaluation.
  7. options() returns the query serialization parameters.
  8. Close the query with close().

PHP Example

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-11, 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");

    // initialize query
    print $query->init();

    // loop through all results
    while($query->more()) {
      print $query->next()."\n";
    }

    // close query instance
    print $query->close();

  } catch (Exception $e) {
    // print exception
    print $e->getMessage();
  }

  // close session
  $session->close();

} catch (Exception $e) {
  // print exception
  print $e->getMessage();
}
?>