Skip to main content

query

Usage: chr query [<options>] <queryname> [<args>]...

  Make a query towards a running node

  Examples:
  ╭─────────────────────────────────────────────────────────────────────╮
  │# query primitive_args(arg1: integer, arg2: name, arg3: text, arg4:  │
  │byte_array, arg5: my_enum)                                           │
  │chr query primitive_args 'arg1=123' 'arg2=Alice' 'arg3="My Neighbor"'│
  │'arg4=x"AB12"' 'arg5=0'                                              │
  │# query dict_arg(arg: map<text, integer>)                            │
  │chr query dict_arg 'arg=["key": 12]'                                 │
  │# query map_arg(arg: map<my_enum, text>)                             │
  │chr query map_arg 'arg=[[0, "first"],[1, "second"]]'                 │
  │# query struct_arg(arg: my_struct)                                   │
  │chr query struct_arg 'arg=[12, "structs are arrays", x"AB"]'         │
  │                                                                     │
  │# Use -- do avoid additional quotes                                  │
  │chr query my_query -- arg1=foo arg2=x"AB12"                          │
  ╰─────────────────────────────────────────────────────────────────────╯

Configuration Properties:
  -cfg, --config=<config>    Alternate path for client configuration file
  -s, --settings=<settings>  Alternate path for project settings file

dApp target options:
  -brid, --blockchain-rid=<text>  Target Blockchain RID
  --cid=<int>                     Target Blockchain IID
  --api-url=<text>                Target api url
  --mainnet, --testnet            Select network, use instead of --api-url

Deployment:

  Use a configured deployment network target in chromia.yml

  -d, --network=<text>      Specify which deployment target to use
  -bc, --blockchain=<text>  Name of blockchain in deployment configuration

Options:
  -f, --output-format=(pretty|raw|JSON|XML|YAML)  Output format
  -h, --help                                      Show this message and exit

Arguments:
  <queryname>  name of the query to make.
  <args>       arguments to pass to the query, passed either as key=value pairs
               or as a single dict. (integer: 123) (big_integer: 1234L)
               (string: foo, "bar") (bytearray: will be encoded using the rell
               notation x"<myByteArray>" and will initially be interpreted as a
               hex-string.) (array: [foo,123]) (dict:
               ["key1":value1,"key2":value2])

You can use the query command (chr query) to test and interact with a chain that's either local or deployed without using a client. You can set a path for the project settings file (chromia.yml) or specify a different file using --settings. If no dApp target or deployment options are used, the command will by default target a local running node that is started with chr node start.

Local Node​

When you start a node, you can see the Blockchain RID as the standard output. An example would look like this: Blockchain RID: FC17B67D66F6F35A5D8B75ED3F83AE222FB8C8FCA241624F06285150F10C6BAC. If you run the node on a different URL than the default http://localhost:7740, you can use the --api-url in the chromia.yml to specify it.

  • To run the query hello_world specified in the main.rell file.
chr query --blockchain-rid <BlockchainRID> hello_world
  • If the query has arguments called foo, bar and baz, then the query would look like the following for the values 17, "hello" and "hello world" (quoting of strings is optional if they don't contain whitespace or special characters).
chr query --blockchain-rid <BlockchainRID> hello_world foo=17 bar=hello 'baz="hello world"'

Deployed​

For deployed chains, you can use the same commands as in a local environment, but you need to target the chain explicitly. You can do this by either:

  • Using a configured deployment target in your chromia.yml together with deployment options
chr query --network deployment_configuration --blockchain my_rell_dapp hello_world
  • Specifying --api-url or --mainnet/--testnet together with the BRID of the dApp you want to query.
chr query --mainnet -brid 2D17B27D4F69E0A91B0CA39AF53EFA9B82CDAF698EF906A67C71C266983EEB7A hello_world