`kusto_tool` API reference

Classes for interacting with a Kusto database.

class kusto_tool.database.Cluster(name)

A class representing a Kusto cluster.

database(name)

Create an instance representing a database in the cluster.

Parameters: name (str) – The name of the Kusto database in the cluster.
Returns: an instance representing the Kusto database.
Return type: KustoDatabase

class kusto_tool.database.KustoDatabase(cluster, database, client=None)

A class representing a Kusto database.

drop_table(table)

Drop a table from the database.

Parameters: table (str) – The name of the table to drop.
Returns: A DataFrame containing the name of the dropped table, indicating success.
Return type: pandas.DataFrame

execute(query: str, *args, **kwargs)

Execute a query or command.

Parameters

query (str) – The text of the Kusto query or command to run. Can also be a path to a file containing a query.
args (List[Any]) – Positional arguments to pass to the query as Jinja2 template params.
kwargs (Dict[Any]) – Keyword arguments to pass to the query as Jinja2 template params.

Returns

A DataFrame containing the query results.

Return type

pandas.DataFrame

set_table(query, table, folder, docstring, *args, **kwargs)

Runs your query and appends or replaces the results to a table.

Parameters

query (str) – The text of the Kusto query to run.
table (str) – The table name to create.
folder (str) – The kusto folder to save the table into.
docstring (str) – The docstring for the table metadata.
replace (bool, default False.) – Appends to the table if True, replaces contents if False.
args (List[Any]) – Positional arguments to pass to the query as Jinja2 template params.
kwargs (Dict[Any]) – Keyword arguments to pass to the query as Jinja2 template params.

Returns

A DataFrame containing the results of the control command.

Return type

pandas.DataFrame

show_tables()

Show the list of tables in the database.

Returns: A DataFrame listing all tables in the database, in the column “TableName”.
Return type: pandas.DataFrame

table(name, columns=None, inspect=False)

A tabular expression.

Parameters

name (str) – The name of the table in the database.
columns (dict or list) – Either: 1. A dictionary where keys are column names and values are data type names, or 2. A list of Column instances.
inspect (bool, default False) – If true, columns will be inspected from the database. If columns list is provided and inspect is true, inspect takes precedence.

Returns

A table expression instance.

Return type

TableExpr

table_exists(table: str) → bool

Check if a table exists in the database.

Parameters: table (str) – The name of the table to look for.
Returns: True if the table exists in the database.
Return type: bool

to_parquet(query, path, *args, force=False, **kwargs)

Run the given query, cache the results as a local parquet file, and return results as a Pandas DataFrame.

Parameters

query (str) – The text of the Kusto query to run.
path (str) – The path to save the parquet file.
force (bool, default False) – If False, the data will be read from the cached parquet file if it exists. If True, the data will be re-downloaded regardless.
args (List[Any]) – Positional arguments to pass to the query as Jinja2 template params.
kwargs (Dict[Any]) – Keyword arguments to pass to the query as Jinja2 template params.

Returns

A DataFrame containing the results of the control command.

Return type

pandas.DataFrame

kusto_tool.database.cluster(name): Convenience function to construct a Cluster instance. Makes the query look more like KQL.

kusto_tool.database.dict_to_datatable(dictionary: dict) → str: Converts a dict to a Kusto datatable statement for use as a lookup table.

kusto_tool.database.list_to_kusto(lst): Convert a Python list to a Kusto list literal.

kusto_tool.database.maybe_read_file(query): Read contents from a file if the argument is a file path.

kusto_tool.database.render_set(query, table, folder, docstring, *args, replace=False, **kwargs) → str: Render a .set-or-[append|replace] command from a query.

kusto_tool.database.render_template_query(query, *args, **kwargs) → str: Render a query with optional parameters.

Experimental Kusto expression API for generating queries.

class kusto_tool.expression.TableExpr(name, database, columns=None, ast=None)

A table or tabular expression.

collect(): Compile the expression to a query, execute it, and return results.

count(): Get the count of rows that would be returned by the expression.

distinct(*args): Distinct values in the given column(s).

evaluate(expr): Evaluate a Kusto plugin expression.

extend(**kwargs)

Add new columns calculated from expressions.

Parameters: kwargs (dict) – Aliased expressions, e.g. foo=”bar”, baz=”quux”

join(right, on, kind, *args, strategy=None)

Join this table expression to another.

Parameters

right (TableExpr) – The table to join this table to.
on ([str]) – The list of columns to join on.
kind (str) – The kind of join. Options: - “inner” - “left” - “right” - “full” - “leftsemi” - “rightsemi” - “leftanti” - “rightanti”
strategy (str, default None) – If “broadcast” then a broadcast join is used. If “shuffle” then a shuffle join is used. If another value or None, a single-node join strategy is used.

limit(n)

Limit the result set to the first n rows.

Parameters: n (int) – The number of rows to return.

mv_expand(column)

Expand a dynamic column into one row per value.

Parameters: column (Column) – The column to expand. Must be a dynamic (or dict or array) column.

order(*args)

Order the result set by the given columns.

Parameters: args (array) – The columns to sort by.

project(*args, **kwargs)

Project (select) a list of columns.

Parameters

args (list) – Column names to project.
kwargs (dict) – Columns to project with renaming, where the key is the new name. Right hand side can be a Column or an expression.

Return type

A table expression.

sample(n)

Randomly sample n rows from the dataset.

Parameters: n (int) – The number of rows to sample.

sample_distinct(n, column)

Randomly sample n rows from the dataset with distinct values in column.

Parameters

n (int) – The number of rows to sample.
column – The column to sample distinct values from.

sort(*args)

Order the result set by the given columns. Alias for .order().

Parameters: args (array) – The columns to sort by.

summarize(by=None, shuffle=False, shufflekey=None, num_partitions=None, **kwargs)

Aggregate by columns.

Parameters

by (list, default None) – List of Column instances or column name strings to group by.
shuffle (bool, default False) – If True, hint.strategy=shuffle will be added to the Kusto query. The shufflekey parameter takes precedence; if it is not None, then shuffle will be ignored.
shufflekey ([str], str, [Column], Column or bool, default None) – Indicates the key to be used for the shuffle summarize strategy. If a string or Column instance, or list thereof, is provided, these columns will be used as the shufflekey; hint.shufflekey=foo, bar will be added to the Kusto query.
num_partitions (int, default None) – A query hint indicating the number of partitions to be used in the shuffle strategy. Has no effect unless shuffle or shufflekey is also provided.
kwargs (Dict) – Aliased aggregation expressions, e.g. bar=foo.sum()

take(n)

Limit the result set to the first n rows. Alias for .limit().

Parameters: n (int) – The number of rows to return.

where(*args): Filter the expression by one or more predicates.

kusto_tool.function.abs_(expr): Absolute value.

kusto_tool.function.acos(expr): Arccosine function.

kusto_tool.function.ago(expr): Subtract a timespan from the current time.

kusto_tool.function.asin(expr): Arcsine function.

kusto_tool.function.atan(expr): Arctangent function.

kusto_tool.function.avg(expr)

Average a column or expression.

Parameters: expr (str, Column or expression.) –

kusto_tool.function.bin_(expr, round_to): Rounds values down to an integer multiple of a given bin size.

kusto_tool.function.ceiling(expr): Rounds up to the smallest integer greater than or equal to expr.

kusto_tool.function.cos(expr): Cosine function.

kusto_tool.function.cot(expr): Cotangent function.

kusto_tool.function.count(): Count rows in the result set.

kusto_tool.function.datetime(expr): Construct a datetime literal.

kusto_tool.function.dcount(expr, accuracy=1)

Distinct count of a column.

Parameters

expr (str, Column or expression.) – The column to apply distinct count to.
accuracy (int, default 1) – The level of accuracy to apply to the hyper log log algorithm. Default is 1, the fastest but least accurate.

kusto_tool.function.decimal(expr): Construct a decimal from a literal.

kusto_tool.function.endofday(expr, offset=None)

Get the end of day for a timestamp (round to 11:59:59.9999999).

Parameters

expr (str, Column or expression.) – The datetime column/expression to round to the end of the day.
offset (int, default None) – The number of days to shift the date by (-1 subtracts a day, 1 adds a day.)

kusto_tool.function.endofmonth(expr, offset=None)

Get the end of the month for a timestamp (round to last day of month at 11:59:59.9999999).

Parameters

expr (str, Column or expression.) – The datetime column/expression to round to the start of the month.
offset (int, default None) – The number of months to shift the date by (-1 subtracts a month, 1 adds a month.)

kusto_tool.function.endofweek(expr, offset=None)

Get the end of the week for a timestamp (round to following Saturday at 11:59:59.9999999).

Parameters

expr (str, Column or expression.) – The datetime column/expression to round to the start of the week.
offset (int, default None) – The number of weeks to shift the date by (-1 subtracts a week, 1 adds a week.)

kusto_tool.function.endofyear(expr, offset=None)

Get the end of the year for a timestamp (round to last day of year at 11:59:59.9999999).

Parameters

expr (str, Column or expression.) – The datetime column/expression to round to the start of the year.
offset (int, default None) – The number of years to shift the date by (-1 subtracts a year, 1 adds a year.)

kusto_tool.function.exp(expr): Exponentiation function e^x.

kusto_tool.function.exp10(expr): Exponentiation function 10^x.

kusto_tool.function.exp2(expr): Exponentiation function 2^x.

kusto_tool.function.floor(expr, round_to): Rounds values down to an integer multiple of a given bin size.

kusto_tool.function.function(name, *args)

Translate to any Kusto function call.

Parameters

name (str) – The name of the Kusto function to call.
args (list) – A list of positional arguments to the function.

kusto_tool.function.gamma(expr): Gamma function.

kusto_tool.function.int_(expr): Construct an int from a string literal.

kusto_tool.function.isfinite(expr): Returns False if expr is infinity (positive or negative).

kusto_tool.function.isinf(expr): Returns True if expr is infinity (positive or negative).

kusto_tool.function.isnan(expr): Returns True if expr is NaN (not a number).

kusto_tool.function.jaccard_index(expr1, expr2): Returns the Jaccard index (intersection over union) of two sets.

kusto_tool.function.log(expr): Returns the natural (base-e) logarithm of expr.

kusto_tool.function.log10(expr): Returns the decimal (base-10) logarithm of expr.

kusto_tool.function.log2(expr): Returns the binary (base-2) logarithm of expr.

kusto_tool.function.loggamma(expr): Returns the logarithm of the absolute value of the gamma function.

kusto_tool.function.long_(expr): Construct a long from a string literal.

kusto_tool.function.mean(expr)

Average a column or expression.

Parameters: expr (str, Column or expression.) –

kusto_tool.function.parse_json(expr): Parse a JSON string to a dynamic.

kusto_tool.function.pi(): Returns the constant pi.

kusto_tool.function.pow_(base, exponent): Raises base to the exponent.

kusto_tool.function.rand(maximum=1.0)

Return a random number between 0 and maximum (default 1.0)

Parameters: maximum (float, default=1.0) – The maximum value for the randomly generated number.

kusto_tool.function.sign(expr): Returns -1 if expr is negative, 0 if zero, or 1 if positive.

kusto_tool.function.sin(expr): Sine function.

kusto_tool.function.sqrt(expr): Square root function.

kusto_tool.function.startofday(expr, offset=None)

Get the start of day for a timestamp (round to preceding midnight).

Parameters

expr (str, Column or expression.) – The datetime column/expression to round to the start of the day.
offset (int, default None) – The number of days to shift the date by (-1 subtracts a day, 1 adds a day.)

kusto_tool.function.startofmonth(expr, offset=None)

Get the start of the month for a timestamp (round to first of the month).

Parameters

expr (str, Column or expression.) – The datetime column/expression to round to the start of the month.
offset (int, default None) – The number of months to shift the date by (-1 subtracts a month, 1 adds a month.)

kusto_tool.function.startofweek(expr, offset=None)

Get the start of the week for a timestamp (round to preceding Sunday at midnight).

Parameters

expr (str, Column or expression.) – The datetime column/expression to round to the start of the week.
offset (int, default None) – The number of weeks to shift the date by (-1 subtracts a week, 1 adds a week.)

kusto_tool.function.startofyear(expr, offset=None)

Get the start of the year for a timestamp (round to first of the year).

Parameters

expr (str, Column or expression.) – The datetime column/expression to round to the start of the year.
offset (int, default None) – The number of years to shift the date by (-1 subtracts a year, 1 adds a year.)

kusto_tool.function.strcat(*args)

String concatenation.

Parameters: args (list) – List of string Columns and/or scalar strings to concatenate.

kusto_tool.function.sum(expr)

Sum a column or expression.

Parameters: expr (str, Column or expression.) –

kusto_tool.function.tan(expr): Tangent function.

kusto_tool.function.time(expr): Construct a timespan from a string literal.

kusto_tool.function.tobool(expr): Convert an expression to boolean.

kusto_tool.function.todatetime(expr): Convert an expression to a datetime.

kusto_tool.function.todecimal(expr): Convert an expression to decimal (fixed point).

kusto_tool.function.todouble(expr): Convert an expression to double (signed 64 bit floating point).

kusto_tool.function.todynamic(expr): Parse a JSON string to a dynamic.

kusto_tool.function.tohex(expr): Converts input to a hexadecimal string.

kusto_tool.function.toint(expr): Converts input to an integer.

kusto_tool.function.tolong(expr): Convert an expression to long (signed 64 bit integer).

kusto_tool.function.toreal(expr): Convert an expression to real (signed 64 bit floating point).

kusto_tool.function.tostring(expr): Converts input to a string.

kusto_tool.function.totimespan(expr): Converts input to a timespan.

kusto_tool API reference

`kusto_tool` API reference