Cliq

Cliq is a python tool that allows you to interact indirectly with our API’s. CLIQ contains a variety of features that are outlined below.

Tql or TqlFlow queries running against IQ or BurstChain®.
It can be run In Interactive Mode or directly from the command line.
Queries can be read from input files and run with the results printing to the console or to an output file.
Existing Dictionaries can be viewed and printed to the console.
Public and Private IDs can be generated directly in CLIQ
Map Reduce Queries can be run against IQ collections.
When querying against a BurstChain® you can specify if you want to query against Assets or Smart Contracts

The Source code is available to download here if you want to expand on what is currently available or explore another way to interact with our API’s using Python.

Download Source Code Here

Setup¶

The CLIQ tool download link is below, once it is downloaded please follow the “Install” instructions in the section below.

Download CLIQ Tool Here

Install and Configure¶

Once you have the package downloaded we will want to install it, to do that first unzip the file, then open a command prompt and navigate to where you downloaded the file.

Once you in the directory that contains the downloaded file you can run the following command with the specific version from the download.

    pip3 install cliq-X.X.X-py3-none-any.whl

This will run through the process for installing Cliq on your machine. Once installed you can run cliq in interactive mode with the command cliq.

If you did not create a cliq_properties.yaml file in your home directory or pass one in when starting up cliq you will be asked if you’d like to generate one.

The Generate process will create a basic cliq_propeties.yaml file with a default profile that can look like the one below:

    userinfo:
      username: yourEamil@email.com # You username/email for authentication
      password: <please enter your password> # Your password associated to the username above

    # profiles for ease of connection
    profiles:
        default:
          url: https://{ASSIGNED_SERVER}.burstiq.com
          client: your_client           # This will be your client name or a client id
          target: iq                    # This will be either iq or BurstChain&reg;
          output_path: /some_filepath/  # This will be a file path to a directory where you want to write query results
          input_path: /some_filepath/   # This will be a file path to a directory that contains a file with a Tql or TqlFlow query
          asset_type: asset             # either asset or smart_contract
          private_id: <your_private_id>
        # Here is what a second profile could look like in the cliq_properties.yaml file.
        other_profile:
            url: https://{ASSIGNED_SERVER}.burstiq.com
            client: your_client
            target: burstchain
            output_path:
            input_path:
            asset_type: smart_contract
            private_id: <your_private_id>

You can always add more profiles to the properties file to allow for easily switching between set configurations.

Using Cliq¶

Cliq has a variety of commands you can run here is a list of the base commands, some commands have sub commands that can be run. Some commands also take arguments that allow you to set specific fields needed to run the command.

(You can see this list by running help):

Command	Description
`help <command>`	Shows a list of commands with a brief description
`exit`	Will Exit CLIQ
`info`	Returns information on the current configuration.
`tql <collection>`	Runs a Tql query.
`flow <collection>`	Runs a TqlFlow query.
`map_reduce <collection>`	Runs a Map Reduce query.
`set <sub-command>`	Sets session values based on the specific sub-command.
`generate <sub-command>`	Used for generating public or private ids based on the sub-command used.
`profile <sub-command>`	Used to run profile sub-commands.
`dict <sub-command>`	Used to run dict sub-commands.

For each of the examples below the console output for each command isn’t shown, the examples just show the command.

—¶

help¶

Shows a list of commands with a brief description

Examples:

cliq> help
cliq> help info
cliq> help tql

exit¶

This will Exit CLIQ.

Example:

cliq> exit

info¶

Returns information on the current configuration.

Example:

cliq> info

tql¶

Runs a Tql query.

<collection> is a required argument and one of either --query or --file is needed.

A full table of arguments is below, the collection/chain needs to immediately follow the main command tql, but after that the arguments can be passed in, in any order.

Argument	Shortened Argument	Description
`<collection>`	N/A	Required - The collection to query against.
`--query`	`-q`	The query to run.
`--file`	`-f`	The file containing the query to run.
`--output`	`-o`	The file name to output the results of the query. If this isn’t used then the results will be printed to the console.
`--username`	`-u`	This will run the query with the username provided in the argument flag instead of the username set for the session.
`--password`	`-p`	This will run the query with the password provided with the argument flag instead of the password set for the session.
`--url`	N/A	This will run the query with the url/host you provide with the argument flag instead of the url/host set for the session.
`--client`	`-c`	This will run the query with the client you provide with the argument flag instead of the client set for the session.
`--private_id`	`-pid`	This will run the query with the private id you provide with the argument flag instead of the private id set for the session.
`--profile`	`-pr`	This will run the query with the profile values from the profile in the cliq_properties file that corresponds to the profile you provide with the argument flag.
`--target`	`-t`	This will run the query with the target you provide with the argument flag instead of the target that is set for the session.
`--asset_type`	`-at`	This will run the query with the asset_type you provide with the argument flag instead of the asset_type that is set for the session.

Examples:

cliq> tql my_chain --query "SELECT * FROM my_chain LIMIT 1"
cliq> tql my_chain --file query.tql --output results.json
cliq> tql my_collection --query "SELECT * FROM my_collection LIMIT 1" --target iq

flow¶

Runs a TqlFlow query.

<collection> is a required argument and one of either --query or --file is needed.

A full table of arguments is below, the collection/chain needs to immediately follow the main command tql, but after that the arguments can be passed in, in any order.

Argument	Shortened Argument	Description
`<collection>`	N/A	Required - The collection to query against.
`--query`	`-q`	The query to run.
`--file`	`-f`	The file containing the query to run.
`--output`	`-o`	The file name to output the results of the query. If this isn’t used then the results will be printed to the console.
`--username`	`-u`	This will run the query with the username provided in the argument flag instead of the username set for the session.
`--password`	`-p`	This will run the query with the password provided with the argument flag instead of the password set for the session.
`--url`	N/A	This will run the query with the url/host you provide with the argument flag instead of the url/host set for the session.
`--client`	`-c`	This will run the query with the client you provide with the argument flag instead of the client set for the session.
`--private_id`	`-pid`	This will run the query with the private id you provide with the argument flag instead of the private id set for the session.
`--profile`	`-pr`	This will run the query with the profile values from the profile in the cliq_properties file that corresponds to the profile you provide with the argument flag.
`--target`	`-t`	This will run the query with the target you provide with the argument flag instead of the target that is set for the session.
`--asset_type`	`-at`	This will run the query with the asset_type you provide with the argument flag instead of the asset_type that is set for the session.

Examples:

cliq> flow my_chain --query "LIMIT 1"
cliq> flow my_chain --file query.flow --output results.json
cliq> flow my_collection --query "LIMIT 1" --target iq

map_reduce¶

Runs a Map Reduce query. A map reduce query can only be run against an IQ collection. BurstChain® queries for Map reduce are not supported at this time.

<collection> is a required argument along with the flag --map_reduce or -mr for short.

The map reduce argument takes filepath or just a filename if your input_path is set for the session. The file contains a json body with the 4 fields(map, reduce, finalize, query), and their values needed to run a map reduce query.

A full table of arguments is below, the collection/chain needs to immediately follow the main command map_reduce, but after that the arguments can be passed in, in any order.

Argument	Shortened Argument	Description
`<collection>`	N/A	Required - The collection to query against.
`--map_reduce`	`-mr`	The map_reduce info needed to run the query.
`--output`	`-o`	The file name to output the results of the query. If this isn’t used then the results will be printed to the console.
`--username`	`-u`	This will run the query with the username provided in the argument flag instead of the username set for the session.
`--password`	`-p`	This will run the query with the password provided with the argument flag instead of the password set for the session.
`--url`	N/A	This will run the query with the url/host you provide with the argument flag instead of the url/host set for the session.
`--client`	`-c`	This will run the query with the client you provide with the argument flag instead of the client set for the session.
`--private_id`	`-pid`	This will run the query with the private id you provide with the argument flag instead of the private id set for the session.
`--profile`	`-pr`	This will run the query with the profile values from the profile in the cliq_properties file that corresponds to the profile you provide with the argument flag.
`--target`	`-t`	This will run the query with the target you provide with the argument flag instead of the target that is set for the session.
`--asset_type`	`-at`	This will run the query with the asset_type you provide with the argument flag instead of the asset_type that is set for the session.

Examples:

cliq> map_reduce my_chain --map_reduce mapper.json
cliq> map_reduce my_chain --map_reduce mapper.json --output results.json
cliq> map_reduce my_collection -mr mapper.json --target iq

set¶

Sets session values based on the specific sub-command.

Set sub-commands

Command	Description
`help <optional_set_sub-command>`	Prints all of the Sub Commands for Set and if you provide a set sub-command after help it will provide a description of the specific sub-command.
`target <target_value>`	Sets the source target either IQ or BurstChain®.
`username <username_value>`	Sets the session username.
`password <password_value>`	Sets the session password.
`client <client_value>`	Sets the session client.
`private_id <private_id_value>`	Sets the session Private ID.
`host_url <host_url_value>`	Sets the Host or Url you are using (defaults to testnet.burstiq.com).
`profile <profile_value>`	Sets the Profile and the values specified under this profile in the cliq_properties.yaml.
`asset_type <asset_type_value>`	Sets the asset type you are querying for, either asset or smart_contract.
`input_path <input_path_value>`	Sets the Input Path, this is a file path to a directory that contains Tql or TqlFlow query files.
`output_path <output_path_value>`	Sets the Filepath to a directory to save output result files.

—¶

help¶

Prints all of the Sub Commands for Set and if you provide a set sub-command after help it will provide a description of the specific sub-command.

Examples:

cliq> set help

Documented Set sub-commands (type "set help <topic>"):
======================================================
client  help  host_url  password  private_id  target  username


cliq> set help target

cliq> set help username

target¶

Sets the source target either IQ or BurstChain®.

Examples:

cliq> set target iq

cliq> set target burstchain

username¶

Sets the session username.

Example:

cliq> set username <new_username@email.com>

password¶

Sets the session password.

Example:

cliq> set password <new_password>

client¶

Sets the session client.

Example:

cliq> set client <new_client_name>

private_id¶

Sets the session Private ID.

Example:

cliq> set private_id <new_private_id>

host_url¶

Sets the Host or Url you are using (defaults to testnet.burstiq.com).

Example:

cliq> set host_url https://aiq.burstiq.com

profile¶

Sets the Profile and the values specified under this profile in the cliq_properties.yaml.

Example:

cliq> set profile default

asset_type¶

Sets the asset type you are querying for, either asset or smart_contract.

Examples:

cliq> set asset_type asset

cliq> set asset_type smart_contract

input_path¶

Sets the Input Path, this is a file path to a directory that contains Tql or TqlFlow query files.

Example:

cliq> set input_path <file_path>

output_path¶

Sets the Filepath to a directory to save output result files.

Example:

cliq> set output_path <file_path>

generate¶

Used for generating public or private ids based on the sub-command used.

Generate sub-commands

Command	Description
`help <optional generate sub-command>`	Prints the sub-commands of Generate and a description if a sub-command argument is provided.
`private_id`	This will generate a new Private ID and print it to the console.
`public_id`	This will return the Public ID for the Private ID set for the session or for the private id passed in with the argument flag.

—¶

help¶

Prints the sub-commands of Generate and a description if a sub-command argument is provided.

Examples:

cliq> generate help
cliq> generate help private_id
cliq> generate help public_id

private_id¶

This will generate a new Private ID and print it to the console.

Example:

cliq> generate private_id

public_id¶

This will return the Public ID for the Private ID set for the session or for the private id passed in with the argument flag.

Examples:

cliq> generate public_id
cliq> generate public_id --private_id <private_id>
cliq> generate public_id -pid <private_id>

profile¶

Used with profile sub commands.

Profile sub-commands

Command	Description
`help <optional help sub-command>`	Prints the sub-commands for Profile and the sub-command description if the optional sub-command argument is provided.
`list`	Prints the profile names that are defined in the cliq_properties file.
`get <profile_name>`	Prints the profile information that is defined in the cliq_properties file for the profile name that is provided.

—¶

help¶

Prints the sub-commands for Profile and the sub-command description if the optional sub-command argument is provided.

Examples:

cliq> profile help
cliq> profile help list
cliq> profile help get

list¶

Prints the profile names that are defined in the cliq_properties file.

Example:

cliq> profile list

get¶

Prints the profile information that is defined in the cliq_properties file for the profile name that is provided.

Example:

cliq> profile get <profile_name>

dict¶

Used to run dict sub-commands.

Dictionary sub-commands

Command	Description
`help <optional dict sub-command>`	Prints the sub-commands for Dictionary and the sub-command description if the optional sub-command argument is provided.
`list`	Prints a list of the current dictionary names for your client.
`get <dictionary_name>`	Looks up the dictionary by its name and prints the dictionary to the console.

—¶

help¶

Prints the sub-commands for Dictionary and the sub-command description if the optional sub-command argument is provided.

Examples:

cliq> dict help
cliq> dict help list
cliq> dict help get

list¶

Prints a list of the current dictionary names for your client.

Example:

cliq> dict list

get¶

Looks up the dictionary by its name and prints the dictionary to the console.

Example:

cliq> dict get <dictionary_name>