[[TOC]] First get the man page of {{{rootifysql}}} either with {{{rootifysql --help}}} or (if installed) with {{{man rootifysql}}}. == Purpose == The idea of {{{rootifysql}}} is to conveniently request data from a MySQL database and write the contents returned into a tree in a root-file. Root trees offer a lot of nice features how to access the data fast and how to create plots easily. For details, please refer either to the Draw-function of TTree (e.g. https://root.cern.ch/doc/master/classTTree.html#a73450649dc6e54b5b94516c468523e45) or checkout the root user manual (https://root.cern.ch/guides/users-guide), in particular the section about '''Trees'''. In the following basic knowledge on C++, {{{root}}} and root trees is assumed. == Connection == How a connection to the database is established is outlined in: DatabaseBasedAnalysis/Connection. Per default, your connection will be compressed if the the host-address of the mysql-server is neither '''localhost''' nor '''127.0.0.1'''. To force compression use {{{ uri fact:password@ihp-pc45.ethz.ch/factdata?compress=1 }}} Generally, compression should be enable if connecting from the world. To test compression, the "''Hello World! ''" example can be used. In the following it is assumed that the database connection is working and tested, so that the resources ({{{uri=...}}}) are omitted. == Hello World! == To test if everything is working correctly, we run a "''Hello World! ''" example. Credentials should be in the rootifysql.rc which should be write protected. {{{ user@machine> rootifysql -d -n --query="SELECT 'Hello World\!'" Reading global options from 'fact++.rc'. Reading default options from 'rootifysql.rc'. ------------------------ Rootify SQL ------------------------- Connecting to database... Client Version: 5.7.23 Server Version: 5.7.23-0ubuntu0.18.04.1 Requesting data... Opening file '/dev/null' [compression=1]... Writing data to tree 'Result' Trying to setup 1 branches... Configured 0 branches. Filling branches... # Hello World! Hello World! 1 rows fetched. 1 rows filled into tree. 0 B written to disk. File closed. Execution time: 0.058136s (58.1 ms/row) -------------------------------------------------------------- }}} Voila! The {{{-d}}} option (a shortcut for {{{--display}}}) prints the result on standard out, the {{{-n}}} option (a shortcut to {{{--null}}}) redirects all output to {{{/dev/null}}} instead to a file. For benchmarking your query, you can also add {{{--no-fill}}} which does not only write to a root tree at {{{/dev/null}}} but does not fill the root tree at all. {{{-q}}} is a shortcut for {{{--query}}} == Query in the file == Instead of typing your query on the command line, you can store in a text-file, for example {{{ user@machine> echo "SELECT 'Hello World\!'" > query.sql user@machine> rootifysql -d -n query.sql [...] ------------------------ Rootify SQL ------------------------- Reading query from file 'query.sql'. [...] # Hello World! Hello World! [...] -------------------------------------------------------------- }}} A nice feature of bash is that you can make the '''query.sql''' file executable. First add the executable in the first line preceded by {{{#!}}}. It might then look like: {{{ #!/path/to/rootifysql SELECT 'Hello World!' }}} Now make it executable for yourself {{{ user@machine> chmod u+x query.sql }}} and you can call your query like {{{ user@machine> ./query.sql [options] }}} with the [options] from {{{rootifysql}}}. If you prefix your query file with {{{ #!/path/to/rootifysql -C /path/to/resources.rc }}} you can even have a dedicated resource file. == Connection information == To get more information on the connection to the database, use {{{--print-connection}}}, for example {{{ user@machine> user@machine> rootifysql -d -n --print-connection query.sql [...] ------------------------ Rootify SQL ------------------------- [...] Compression of database connection is ON Connection to databases is ENCRYPTED (DHE-RSA-AES256-SHA) [...] -------------------------------------------------------------- Bytes_sent 398 Bytes_received 546 }}} Note that this data is retrieved through additional requests, which in principle slow down the execution time and add additional traffic to the connection. == Writing to an ASCII file == We can redirect the result of the query to an ASCII file by {{{ rootifysql -v 0 -d -n query.sql > output.txt }}} A verbosity level of 0 ({{{-v 0}}}) is required to turn off all the other output to standard out. If you want to keep it you can directly write to a file by {{{ rootifysql -n query.sql -w output.txt }}} Here {{{-w}}} is a shortcut to {{{--write}}}. The default delimiter is a tab ({{{\t}}}). It can be changed with {{{-d}}} (short for {{{--delimiter}}}) == Writing to a root-file == === Basics === Let's try our previous example {{{ fact@ihp-pc45:~/FACT++/build> rootifysql -f -v 2 -q "SELECT 'Hello World\!'" [...] ------------------------ Rootify SQL ------------------------- [...] Opening file 'rootify.root' [compression=1]... Writing data to tree 'Result' Trying to setup 1 branches... - Hello World! [VARCHAR NOT NULL] {V} Configured 0 branches. Filling branches... 1 rows fetched. 1 rows filled into tree. 4 kB written to disk. File closed. Execution time: 0.0775619s (77.6 ms/row) -------------------------------------------------------------- }}} The option {{{-f}}} (which is a shortcut for {{{--force}}}) actually overwrites an existing root file (''RECREATE''). The verbosity option {{{-v 2}}} prints some information on how the table columns are translated. As the output suggests, 1 branch could have been setup (one column was returned), but no branch was configured. Our "''Hello World!''" string is returned as a VARCHAR (or CHAR), but only values are supported. The leading {{{-}}} tells us that the column was skipped, the {{{V}}} is an internal abbreviation for the action (and {{{C}}} for {{{CHAR}}}). So second try: {{{ fact@ihp-pc45:~/FACT++/build> rootifysql -f -v 2 -q "SELECT 'Hello World\!', 1" [...] ------------------------ Rootify SQL ------------------------- [...] Opening file 'rootify.root' [compression=1]... Writing data to tree 'Result' Trying to setup 2 branches... - Hello World! [VARCHAR NOT NULL] {V} + 1 [BIGINT NOT NULL] {n} Configured 1 branches. Filling branches... 1 rows fetched. 1 rows filled into tree. 5 kB written to disk. File closed. Execution time: 0.064065s (64.1 ms/row) -------------------------------------------------------------- }}} Now one branch was setup successfully (indicated by the {{{+}}}) because it of a basic (numerical) type (indicated by the {{{n}}}). All columns of a numerical type ({{{n}}}) get converted to a branch of type double in the root-file. This keeps reading the root-file simple. All SQL columns of types {{{DATE}}}, {{{DATETIME}}} and {{{TIME}}} are converted to UNIX time and also written as a double-branch. To have another way to skip columns, all variables defined in a query are skipped: {{{ fact@ihp-pc45:~/FACT++/build> rootifysql -f -v 2 -q "SELECT 'Hello World\!', 1, @a:=5" [...] ------------------------ Rootify SQL ------------------------- [...] Trying to setup 3 branches... - Hello World! [VARCHAR NOT NULL] {V} + 1 [BIGINT NOT NULL] {n} - @a:=5 [BIGINT NOT NULL] {@} 1 branches skipped due to name starting with @. Configured 1 branches. [...] -------------------------------------------------------------- }}} === Some general root file options === The output file name can be changed with {{{--out}}} and the tree name with {{{--tree}}}. {{{ fact@ihp-pc45:~/FACT++/build> rootifysql -f -q "SELECT 1" --out newfile.root --tree MyTree [...] Opening file 'newfile.root' [compression=1]... Writing data to tree 'MyTree' [...] }}} To update en existing file use {{{--update}}}. {{{ fact@ihp-pc45:~/FACT++/build> rootifysql --update -q "SELECT 1" --out newfile.root --tree MyNewTree [...] Opening file 'newfile.root' [compression=1]... Writing data to tree 'MyTree' [...] }}} Note that this will always create a new tree in an existing file. You can not update an existing tree. The compression can be changed with {{{-c}}} (short for {{{--compression}}}) {{{ fact@ihp-pc45:~/FACT++/build> rootifysql -c 9--query="SELECT 1" [...] Opening file 'rootifysql.root' [compression=9]... [...] }}} === Changing the branch name === This can be circumvented by giving it a name {{{ fact@ihp-pc45:~/FACT++/build> rootifysql -f -v 2 -q "SELECT 'Hello World\!', 1, @a:=5 AS MyName" [...] ------------------------ Rootify SQL ------------------------- [...] Trying to setup 3 branches... - Hello World! [VARCHAR NOT NULL] {V} + 1 [BIGINT NOT NULL] {n} + MyName [BIGINT NOT NULL] {n} Configured 2 branches. [...] -------------------------------------------------------------- }}} Usually the name of the root-branch coincides with the name of the column, but it can easily be overwritten in the query with the {{{AS}}} directive as illustrated above. === Ignoring columns === Now assuming you want to create a very general query but then skip some column in the root-file (usually, it is more efficient to just don't query them, because they are transferred from the server nevertheless). In this case you can do: {{{ user@machine> rootifysql -f -v 2 -q "SELECT 'Hello World\!', 1, @a:=5 AS MyName" --ignore MyName [...] ------------------------ Rootify SQL ------------------------- [...] Trying to setup 3 branches... - Hello World! [VARCHAR NOT NULL] {V} + 1 [BIGINT NOT NULL] {n} - MyName [BIGINT NOT NULL] {-} 1 branches skipped due to ignore list. Configured 1 branches. [...] -------------------------------------------------------------- }}} The {{{--ignore}}} option can be specified more than once and it takes regular expression. So {{{--ignore M.*}}} would skip all columns starting with '''My'''. === Ignoring NULL === Datanse tables can contain field without an entry (or with '''NULL''' as an entry). A root-branch is not able to represent ''no entry''. Therefore, rows which contain any field with NULL are skipped as a default. {{{ user@machine> rootifysql -n -d -q "SELECT NULL AS Col0, 1 AS Col1, 2 AS Col2" --ignore Col0 [...] ------------------------ Rootify SQL ------------------------- [...] Trying to setup 3 branches... 1 branches skipped due to ignore list. Configured 2 branches. Filling branches... # Col0 Col1 Col2 1 rows fetched. 1 rows skipped due to NULL field. 0 rows filled into tree. 0 B written to disk. File closed. Execution time: 0.0586302s (58.6 ms/row) -------------------------------------------------------------- }}} Note that this is even true for columns which contain NULL in a field which is only requested but not written to the file later on as you can see in the example above. Skipping rows with NULL fields can be turned off by the {{{-i}}} (short for {{{--ignore-null}}}) option. {{{ user@machine> rootifysql -n -d -i -q "SELECT NULL AS Col0, 1 AS Col1, 2 AS Col2" [...] ------------------------ Rootify SQL ------------------------- [...] Opening file '/dev/null' [compression=1]... Writing data to tree 'Result' Trying to setup 3 branches... Configured 3 branches. Filling branches... # Col0 Col1 Col2 NULL 1 2 1 rows fetched. 1 rows filled into tree. 0 B written to disk. File closed. Execution time: 0.0561399s (56.1 ms/row) -------------------------------------------------------------- }}} All fields containing NULL will be written with a 0-value. == User Variables == MySQL supports user variables which can be used in a query. They can be set using the {{{--var.*}}} option, for example {{{ user@machine> rootifysql -n -d -v 3 -q "SELECT @myvar" --var.myvar=42 [...] ------------------------ Rootify SQL ------------------------- [...] Setting user defined variables... SET @myvar:=42 Requesting data... SELECT @myvar Opening file '/dev/null' [compression=1]... Writing data to tree 'Result' Trying to setup 1 branches... - @myvar [BIGINT NULL] {@} 1 branches skipped due to name starting with @. Configured 0 branches. Filling branches... # @myvar 42 1 rows fetched. 1 rows filled into tree. 0 B written to disk. File closed. Execution time: 0.0547669s (54.8 ms/row) -------------------------------------------------------------- }}} The {{{-var.*}}} option can be specified more than once for different variables. This shows another feature. Setting the verbosity level to 3 prints the user queries (not the internal ones). == Environment variables == Instead of using SQL user variables, a replacement can be done. Instead of {{{--var.*}}}, this is done with {{{--env.*}}}. Replaced are $ENV and ${ENV}. Note that the replacement is done linear, so recursive replacement is not foreseen. Here is an example: {{{ user@machine> rootifysql -n -d -v 3 -q "SELECT \$myvar1, \${myvar2}, '\$myvar3'" --env.myvar1=1 --env.myvar2=2 --env.myvar3=3 --env.myvar3=4 [...] ------------------------ Rootify SQL ------------------------- [...] Requesting data... SELECT 1, 2, '3, 4' Opening file '/dev/null' [compression=1]... Writing data to tree 'Result' Trying to setup 3 branches... + 1 [BIGINT NOT NULL] {n} + 2 [BIGINT NOT NULL] {n} - 3, 4 [VARCHAR NOT NULL] {V} Configured 2 branches. Filling branches... # 1 2 3, 4 1 2 3, 4 1 rows fetched. 1 rows filled into tree. 0 B written to disk. File closed. Execution time: 0.055017s (55.0 ms/row) -------------------------------------------------------------- }}} This example also illustrates that if one environment variable is specified more than once, a comma-separated list is created. This is especially useful together with the SQL {{{IN}}} statement. Please be aware that if you specify a query on the command line, you have to escape the {{{$}}} to {{{\$}}}, otherwise they will be replaced already by the shell with the shell's environment variables. An alternative to specifying environment variables on the command line is to read them from a file with {{{--list.*}}}. Each line (except empty lines and lines starting with {{{#}}}) are considered a single value. Let's assume the file '''input.txt''' contains the following {{{ # This is input.txt 42 21 10.5 }}} you can do {{{ user@machine> rootifysql -n -d -v 3 -q "SELECT \$myvar" --list.myvar=input.txt [...] ------------------------ Rootify SQL ------------------------- Found 3 list element(s) for ${myvar} [...] Requesting data... SELECT 42, 21, 10.5 Opening file '/dev/null' [compression=1]... Writing data to tree 'Result' Trying to setup 3 branches... + 42 [BIGINT NOT NULL] {n} + 21 [BIGINT NOT NULL] {n} + 10.5 [DECIMAL NOT NULL] {n} Configured 3 branches. Filling branches... # 42 21 10.5 42 21 10.5 1 rows fetched. 1 rows filled into tree. 0 B written to disk. File closed. Execution time: 0.0551879s (55.2 ms/row) -------------------------------------------------------------- }}} Note that {{{--env.*}}} and {{{--list.*}}} can be mixed. == Explain and profiling == The {{{--explain}}} option request the server to explain ({{{EXPLAIN}}}) the query. The result is displayed as JSON and as standard data. In addition the returned optimized query is displayed. Some simple formatting is done for an easier readability. This is ''preliminary''. Please report any problems The {{{--profiling}}} option turns on profiling ({{{SET PROFILING=1}}}) and request the profile ({{{SHOW PROFILE}}}) of the main query afterwards and shows it on the console. == Returns == In case of success, {{{rootifysql}}} returns 0, a value>0 otherwise.