Name
explain — describe SQL statement compilation
Synopsis
explain
(
|
in text varchar , |
in
cursor_type
integer
); |
Description
The explain function compiles a SQL statement and returns a description of that compilation as a result set, return value or parse tree. The result set consists of one VARCHAR column with one line of the description in each row. Any given line may be quite long, even several hundred characters.
The output is not a complete disassembly of the query graph, but it is detailed enough to show the join order, the sub-query structure, and the order of evaluation of query predicates, as well as the splitting of a distributed VDB query over different data sources.
The optional cursor type can be one of the SQL_CURSOR_<xx> constants, or one of the special values listed below. The default is 0, for FORWARD ONLY. The special values each have special effect, as listed. If the statement is a SELECT and the cursor type is not FORWARD ONLY, the auxiliary SQL statements used by the cursor implementation are shown.
Table 24.30. Cursor Type
| Cursor Type | Effect |
|---|---|
| 3 | SQL_CURSOR_STATIC |
| 2 | SQL_CURSOR_DYNAMIC |
| 1 | SQL_CURSOR_KEYSET_DRIVEN |
| 0 | SQL_CURSOR_FORWARD_ONLY |
| -1 | A result set is printed. Same effect as 0. |
| -2 | A parse tree is returned. |
| -5 | A result set is printed, and a diagnostic dump is delivered to the server's standard output. This can be viewed if the server was started with +foreground option. |
| -7 | Cost estimates are returned, associated with any different join orders tried during the compilation. |
Parameters
text
varchar SQL statement
cursor_type
integer cursor type
Return Types
Returns types vary with the specified cursor type.
Table 24.31. Return Types
| Cursor Type | Return Type |
|---|---|
| 0, 1, 2, 3, -5, -1 | Result set. |
| -7 | Return value. |
| -2 | Parse tree. |
Examples
Example 24.108. Simple Example Usage
Execute from ISQL:
SQL> explain('select * from sys_users');
REPORT
VARCHAR
_______________________________________________________________________________
{
from DB.DBA.SYS_USERS by SYS_USERS 17 rows
Key SYS_USERS ASC ($47 ".U_ID", $46 ".U_NAME", $45 ".U_IS_ROLE", $44 ".U_FULL_NAME", $43 ".U_E_MAIL", $42 ".U_PASSWORD", $41 ".U_GROUP", $40 ".U_LOGI
N_TIME", $39 ".U_ACCOUNT_DISABLED", $38 ".U_DAV_ENABLE", $37 ".U_SQL_ENABLE", $36 ".U_DATA", $35 ".U_METHODS", $34 ".U_DEF_PERMS", $33 ".U_HOME", $32
".U_PASSWORD_HOOK", $31 ".U_PASSWORD_HOOK_DATA", $30 ".U_GET_PASSWORD", $29 ".U_DEF_QUAL", $28 ".U_OPTS")
Current of: <$49 "<DB.DBA.SYS_USERS >" spec 5>
Select ($47 ".U_ID", $46 ".U_NAME", $45 ".U_IS_ROLE", $44 ".U_FULL_NAME", $43 ".U_E_MAIL", $42 ".U_PASSWORD", $41 ".U_GROUP", $40 ".U_LOGIN_TIME", $39
".U_ACCOUNT_DISABLED", $38 ".U_DAV_ENABLE", $37 ".U_SQL_ENABLE", $36 ".U_DATA", $35 ".U_METHODS", $34 ".U_DEF_PERMS", $33 ".U_HOME", $32 ".U_PASSWORD
_HOOK", $31 ".U_PASSWORD_HOOK_DATA", $30 ".U_GET_PASSWORD", $29 ".U_DEF_QUAL", $28 ".U_OPTS", <$49 "<DB.DBA.SYS_USERS >" spec 5>)
}
8 Rows. -- 10 msec.
Example 24.109. Example with type -1
Execute from ISQL:
SQL> explain('sparql
select *
from <http://myopenlink.net/dataspace/person/kidehen#this>
where {?s ?p ?o} limit 10',-1);
REPORT
VARCHAR
_______________________________________________________________________________
{
Precode:
0: $27 "hen#this" := Call iri_to_id_nosignal (<constant (http://myopenlink.net/dataspace/person/kidehen#this)>)
5: BReturn 0
from DB.DBA.RDF_QUAD by RDF_QUAD 0.4 rows
Key RDF_QUAD ASC ($31 "s-1-1-t0.S", $30 "s-1-1-t0.P", $29 "s-1-1-t0.O")
inlined <col=412 G = $27 "hen#this">
Current of: <$33 "<DB.DBA.RDF_QUAD s-1-1-t0>" spec 5>
After code:
0: $34 "s" := Call id_to_iri ($31 "s-1-1-t0.S")
5: $35 "p" := Call id_to_iri ($30 "s-1-1-t0.P")
10: $36 "o" := Call __rdf_sqlval_of_obj ($29 "s-1-1-t0.O")
15: BReturn 0
Select (TOP <constant (10)>) ($34 "s", $35 "p", $36 "o", <$33 "<DB.DBA.RDF_QUAD s-1-1-t0>" spec 5>)
}
18 Rows. -- 10 msec.
Example 24.110. Example with type -2
Execute from ISQL:
SQL> select dbg_obj_print(explain('sparql
select *
from <http://myopenlink.net/dataspace/person/kidehen#this>
where {?s ?p ?o} limit 10',-2));
callret
VARCHAR
_______________________________________________________________________________
0
1 Rows. -- 20 msec.
As result on the Server console will be shown this output:
(100 (122 0 10 0 0 0 ) ((21 (609 'id_to_iri' ((201 's-1-1-t0' 'S' ) ) ) 0 's' 0 ) (21 (609 'id_to_iri' ((201 's-1-1-t0' 'P' ) ) ) 0 'p' 0 ) (21 (609 '
__rdf_sqlval_of_obj' ((201 's-1-1-t0' 'O' ) ) ) 0 'o' 0 ) ) 0 (106 ((107 (200 'DB.DBA.RDF_QUAD' 's-1-1-t0' 0 0 0 ) 0 ) ) (9 (201 's-1-1-t0' 'G' ) (609
'iri_to_id_nosignal' ('http://myopenlink.net/dataspace/person/kidehen#this' ) ) 0 0 0 0 0 0 ) 0 0 0 0 (907 1 ) 0 ) )
Example 24.111. Example with type -5
Execute from ISQL:
SQL> explain('sparql select * from <http://myopenlink.net/dataspace/person/kidehen#this> where {?s ?p ?o} limit 10',-5);
REPORT
VARCHAR
_______________________________________________________________________________
{
Precode:
0: $27 "hen#this" := Call iri_to_id_nosignal (<constant (http://myopenlink.net/dataspace/person/kidehen#this)>)
5: BReturn 0
from DB.DBA.RDF_QUAD by RDF_QUAD 0.4 rows
Key RDF_QUAD ASC ($31 "s-1-1-t0.S", $30 "s-1-1-t0.P", $29 "s-1-1-t0.O")
inlined <col=412 G = $27 "hen#this">
Current of: <$33 "<DB.DBA.RDF_QUAD s-1-1-t0>" spec 5>
After code:
0: $34 "s" := Call id_to_iri ($31 "s-1-1-t0.S")
5: $35 "p" := Call id_to_iri ($30 "s-1-1-t0.P")
10: $36 "o" := Call __rdf_sqlval_of_obj ($29 "s-1-1-t0.O")
15: BReturn 0
Select (TOP <constant (10)>) ($34 "s", $35 "p", $36 "o", <$33 "<DB.DBA.RDF_QUAD s-1-1-t0>" spec 5>)
}
18 Rows. -- 40 msec.
As result on the Server console will be printed this output:
New best dt0 is:
sequence for dt0 cost 6.9 (0.0135757 msec):RDF_QUAD as t1 on RDF_QUAD ,
{
dt dt0
unit 6.9 (0.0135757 msecs) arity 0.4 reached 1
Out cols :
call id_to_iri: (609 'id_to_iri' ((201 't1' 'S' ) ) )
call id_to_iri: (609 'id_to_iri' ((201 't1' 'P' ) ) )
call __rdf_sqlval_of_obj: (609 '__rdf_sqlval_of_obj' ((201 't1' 'O' ) ) )
call iri_to_id_nosignal: (609 'iri_to_id_nosignal' ('http://myopenlink.net/dataspace/person/kidehen#this' ) )
Table DB.DBA.RDF_QUAD(s-1-1-t0 t1) by RDF_QUAD Reached 1 unit 4.6 (0.00907572 msecs) arity 0.4
col preds:
pred artm (201 't1' 'G' ) = (609 'iri_to_id_nosignal' ('http://myopenlink.net/dataspace/person/kidehen#this' ) )
out cols: O P S
call id_to_iri: (609 'id_to_iri' ((201 't1' 'S' ) ) )
call id_to_iri: (609 'id_to_iri' ((201 't1' 'P' ) ) )
call __rdf_sqlval_of_obj: (609 '__rdf_sqlval_of_obj' ((201 't1' 'O' ) ) )
}
Example 24.112. Example with type -7
Execute from ISQL:
SQL> select explain('sparql
select *
from <http://myopenlink.net/dataspace/person/kidehen#this>
where {?s ?p ?o} limit 10',-7);
callret
VARCHAR
_______________________________________________________________________________
6.957722663879395
1 Rows. -- 0 msec.
Example 24.113. Example with vsp printing the result from executing explain:
<?vsp
declare meta, data any;
exec ('explain (?)', null, null, vector ('select * from sys_users'), 0, meta, data);
foreach (any row in data) do
{
http_value (row[0], 'p');
}
?>
Equivalent is:
<?vsp
declare meta, data any;
exec ('explain (?)', null, null, vector ('select * from sys_users'), 0, meta, data);
for (declare i,l int, i := 0, l := length (data); i < l; i := i + 1)
{
http_value (data[i][0], 'p');
}
?>
?>
As result, after accessing this sample vsp, the following output will be printed:
{
from DB.DBA.SYS_USERS by SYS_USERS 17 rows
Key SYS_USERS ASC ($47 ".U_ID", $46 ".U_NAME", $45 ".U_IS_ROLE", $44 ".U_FULL_NAME", $43 ".U_E_MAIL", $42 ".U_PASSWORD", $41 ".U_GROUP", $40 ".U_LOGIN_TIME", $39 ".U_ACCOUNT_DISABLED", $38 ".U_DAV_ENABLE", $37 ".U_SQL_ENABLE", $36 ".U_DATA", $35 ".U_METHODS", $34 ".U_DEF_PERMS", $33 ".U_HOME", $32 ".U_PASSWORD_HOOK", $31 ".U_PASSWORD_HOOK_DATA", $30 ".U_GET_PASSWORD", $29 ".U_DEF_QUAL", $28 ".U_OPTS")
Current of: <$49 "<DB.DBA.SYS_USERS >" spec 5>
Select ($47 ".U_ID", $46 ".U_NAME", $45 ".U_IS_ROLE", $44 ".U_FULL_NAME", $43 ".U_E_MAIL", $42 ".U_PASSWORD", $41 ".U_GROUP", $40 ".U_LOGIN_TIME", $39 ".U_ACCOUNT_DISABLED", $38 ".U_DAV_ENABLE", $37 ".U_SQL_ENABLE", $36 ".U_DATA", $35 ".U_METHODS", $34 ".U_DEF_PERMS", $33 ".U_HOME", $32 ".U_PASSWORD_HOOK", $31 ".U_PASSWORD_HOOK_DATA", $30 ".U_GET_PASSWORD", $29 ".U_DEF_QUAL", $28 ".U_OPTS", <$49 "<DB.DBA.SYS_USERS >" spec 5>)
}
?>