\triagens\ArangoDbStatement

Container for a read-only ("select") statement

A statement is an AQL query that can be issued to the server. Optional bind parameters can be used when issuing the statement to separate the statement from the values. Executing a statement will result in a cursor being created.

There is an important distinction between two different types of statements:

  • statements that produce a list of documents as their result AND
  • statements that do not produce documents

For example, a statement such as "FOR e IN example RETURN e" will produce a list of documents as its result. The result can be treated as a list of documents, and the document can be updated and sent back to the server by the client.

However, the query "RETURN 1 + 1" will not produce a list of documents as its result, but a list with a single scalar value (the number 2). "2" is not a valid document so creating a document from it will fail.

To turn the results of this query into a document, the following needs to be done:

  • modify the query to "RETURN { value: 1 + 1 }". The result will then be a a list of documents with a "value" attribute
  • use the "_flat" option for the statement to indicate that you don't want to treat the statement result as a list of documents, but as a flat list


Summary

Methods
Properties
Constants
__construct()
execute()
explain()
validate()
__invoke()
__toString()
bind()
getBindVars()
setQuery()
getQuery()
setResulType()
setCount()
getCount()
setFullCount()
getFullCount()
setBatchSize()
getBatchSize()
No public properties found
ENTRY_QUERY
ENTRY_COUNT
ENTRY_BATCHSIZE
ENTRY_BINDVARS
FULL_COUNT
getConnection()
No protected properties found
N/A
buildData()
getCursorOptions()
$_connection
$_bindVars
$_batchSize
$_doCount
$_fullCount
$_query
$_flat
$_sanitize
$resultType
N/A

Constants

ENTRY_QUERY

ENTRY_QUERY

Query string index

ENTRY_COUNT

ENTRY_COUNT

Count option index

ENTRY_BATCHSIZE

ENTRY_BATCHSIZE

Batch size index

ENTRY_BINDVARS

ENTRY_BINDVARS

Bind variables index

FULL_COUNT

FULL_COUNT

Full count option index

Properties

$_bindVars

$_bindVars : \triagens\ArangoDb\BindVars

The bind variables and values used for the statement

Type

\triagens\ArangoDb\BindVars

$_batchSize

$_batchSize : mixed

The current batch size (number of result documents retrieved per round-trip)

Type

mixed

$_doCount

$_doCount : boolean

The count flag (should server return total number of results)

Type

boolean

$_fullCount

$_fullCount : boolean

The count flag (should server return total number of results ignoring the limit) Be careful! This option also prevents ArangoDB from using some server side optimizations!

Type

boolean

$_query

$_query : string

The query string

Type

string

$_flat

$_flat : boolean

"flat" flag (if set, the query results will be treated as a simple array, not documents)

Type

boolean

$_sanitize

$_sanitize : boolean

Sanitation flag (if set, the _id and _rev attributes will be removed from the results)

Type

boolean

$resultType

$resultType : string

resultType

Type

string

Methods

__construct()

__construct(\triagens\ArangoDb\Connection $connection, array $data)

Initialise the statement

The $data property can be used to specify the query text and further options for the query.

An important consideration when creating a statement is whether the statement will produce a list of documents as its result or any other non-document value. When a statement is created, by default it is assumed that the statement will produce documents. If this is not the case, executing a statement that returns non-documents will fail.

To explicitly mark the statement as returning non-documents, the '_flat' option should be specified in $data.

Parameters

\triagens\ArangoDb\Connection $connection
  • the connection to be used
array $data
  • statement initialization data

Throws

\triagens\ArangoDb\Exception

execute()

execute() : \triagens\ArangoDb\Cursor

Execute the statement

This will post the query to the server and return the results as a Cursor. The cursor can then be used to iterate the results.

Throws

\triagens\ArangoDb\Exception

Returns

\triagens\ArangoDb\Cursor

explain()

explain() : Array

Explain the statement's execution plan

This will post the query to the server and return the execution plan as an array.

Throws

\triagens\ArangoDb\Exception

Returns

Array

validate()

validate() : Array

Validates the statement

This will post the query to the server for validation and return the validation result as an array.

Throws

\triagens\ArangoDb\Exception

Returns

Array

__invoke()

__invoke(mixed $args) : \triagens\ArangoDb\Cursor

Invoke the statement

This will simply call execute(). Arguments are ignored.

Parameters

mixed $args
  • arguments for invocation, will be ignored

Throws

\triagens\ArangoDb\Exception

Returns

\triagens\ArangoDb\Cursor
  • the result cursor

__toString()

__toString() : string

Return a string representation of the statement

Returns

string —
  • the current query string

bind()

bind(mixed $key, mixed $value) : void

Bind a parameter to the statement

This method can either be called with a string $key and a separate value in $value, or with an array of all bind bind parameters in $key, with $value being NULL.

Allowed value types for bind parameters are string, int, double, bool and array. Arrays must not contain any other than these types.

Parameters

mixed $key
  • name of bind variable OR an array of all bind variables
mixed $value
  • value for bind variable

Throws

\triagens\ArangoDb\Exception

getBindVars()

getBindVars() : array

Get all bind parameters as an array

Returns

array —
  • array of bind variables/values

setQuery()

setQuery(string $query) : void

Set the query string

Parameters

string $query
  • query string

Throws

\triagens\ArangoDb\ClientException

getQuery()

getQuery() : string

Get the query string

Returns

string —
  • current query string value

setResulType()

setResulType( $resultType) : string

setResultType

Parameters

$resultType

Returns

string —
  • resultType of the query

setCount()

setCount(boolean $value) : void

Set the count option for the statement

Parameters

boolean $value
  • value for count option

getCount()

getCount() : boolean

Get the count option value of the statement

Returns

boolean —
  • current value of count option

setFullCount()

setFullCount(boolean $value) : void

Set the full count option for the statement

Parameters

boolean $value
  • value for full count option

getFullCount()

getFullCount() : boolean

Get the full count option value of the statement

Returns

boolean —
  • current value of full count option

setBatchSize()

setBatchSize(integer $value) : void

Set the batch size for the statement

The batch size is the number of results to be transferred in one server round-trip. If a query produces more results than the batch size, it creates a server-side cursor that provides the additional results.

The server-side cursor can be accessed by the client with subsequent HTTP requests.

Parameters

integer $value
  • batch size value

Throws

\triagens\ArangoDb\ClientException

getBatchSize()

getBatchSize() : integer

Get the batch size for the statement

Returns

integer —
  • current batch size value

getConnection()

getConnection() : \triagens\ArangoDb\Connection

Return the connection object

Returns

\triagens\ArangoDb\Connection
  • the connection object

buildData()

buildData() : array

Build an array of data to be posted to the server when issuing the statement

Returns

array —
  • array of data to be sent to server

getCursorOptions()

getCursorOptions() : array

Return an array of cursor options

Returns

array —
  • array of options