.. _queryargs:
Query Arguments
****************

This section contains arguments that are used at certain level during the execution of a function that does not necessarily correspond to the function's API.
*Command options* affect the current command execution while *execution options* generally refer to global options.
Separately, *upload options* only apply to upload commands, like :func:`.upload_pandas_dataframe` and :func:`.read_parquet`.

Command options
-----------------

- **name** (*str, optional*) - symbolic name for the table resulting from the computation
- **dummy_for** (*str, optional*) - Handle as string of 64 hexadecimal characters. This indicates that the table resulting from this computation should be interpreted as dummy data for the specified handle. May not be specified if ``name`` is also specified.
- **mode** (*str* (``"open"`` / ``"defer"`` / ``"regular"``), *default:* ``"regular"``) - mode in which to perform queries that return objects:
    - ``"regular"``: perform computation and wait, return metadata
    - ``"open"``:  perform computation and return opened result
    - ``"defer"``: initate computation, do not wait for result
- **add_nonce** (*bool, default: ``False``*) - if ``True``, add a nonce to the query so that it is guaranteed to be recomputed (instead of possibly re-using a cached result)
- **bitlength** (*any*) - Ignored for backward compatibility
- **_keep** (*bool*) - if ``False``, table is not saved
- **_return_job** (*bool, default* ``False``) - (internal) return ``Query`` object instead of result

Execution options
-----------------

All execution options are optional; if not given, the default value from
the session is used (e.g., if `print_json` is `None`, then `session.print_json` is used).

- **print_json** (*bool/str/None*) - Whether the query JSONs should be recorded
    - *If* ``None``, *use value from session (default:* ``False``)
    - If ``True``, print JSON representations of performed queries to ``sys.stdout``
    - If it is a string representing a file name, append to the corresponding file.
- **authorization_file** (*str/None*) - Name of file containing authorization(s) used to authorize the query.
    - *If* ``None``, *use value from session (default:* ``False``)
    - If ``False``, then the query is sent without authorization
- **dry_run** (*bool/None*) - is it a dry run of the process
    - *If* ``None``, *use value from session (default:* ``False``) 
    - If ``True``, perform a dry run: do not actually perform the queries but instead return dummy values with of the type of the query result.
- **authorizations** (*JSON-serializable list/* ``None``) - A list of signed query to match authorization against.
    *If* ``None``, *use queries from currently running script*
- **session** (*session object/* ``None``) - ``Session`` object to use
    *If* ``None``, *use* ``crandas.base.session``
- **_return_job** (*bool*) - (internal) 
    If set to ``True``, return query object instead of query result, for testing purposes. If set, no bulk data is uploaded

Upload options
--------------

These arguments apply to uploads:

- **auto_bounds** (*bool, default:* ``False``, the default is configurable by ``config.settings.auto_bounds``, see :mod:`crandas.config`) if True, do not warn about data-derived column bounds.

  It is recommended to always manually supply ctypes and the bounds
  therein for all columns, to avoid unintentionally leaking information
  about the data (for example, the maximum length of a string). For ease
  of use, the system does allow omitting the ctypes, and deriving them
  and the bounds from the data. However, to make sure the user intended
  for this, the default behavior is to print a warning whenever a bound
  was automatically derived from the data. Setting this parameter (or the
  session or configuration variable) to ``True`` disables the warning.