fireant.queries package

Submodules

fireant.queries.builder module

class fireant.queries.builder.DataSetQueryBuilder(dataset)

Bases: fireant.queries.builder.QueryBuilder

Slicer queries consist of widgets, dimensions, filters, and references. At least one or more widgets is required. All others are optional.

dimension(*args, mutate=False, **kwargs)

Parameters:mutate – When True, overrides the immutable behavior of this decorator.

fetch(hint=None) → Iterable[Dict]

Fetch the data for this query and transform it into the widgets.

Parameters:hint – A query hint label used with database vendors which support it. Adds a label comment to the query. Returns:A list of dict (JSON) objects containing the widget configurations.

orderby(*args, mutate=False, **kwargs)

Parameters:mutate – When True, overrides the immutable behavior of this decorator.

plot()

reference(*args, mutate=False, **kwargs)

Parameters:mutate – When True, overrides the immutable behavior of this decorator.

reference_groups

sql

Serialize this query builder to a list of Pypika/SQL queries. This function will return one query for every combination of reference and rolled up dimension (including null options).

This collects all of the metrics in each widget, dimensions, and filters and builds a corresponding pypika query to fetch the data. When references are used, the base query normally produced is wrapped in an outer query and a query for each reference is joined based on the referenced dimension shifted.

widget(*args, mutate=False, **kwargs)

Parameters:mutate – When True, overrides the immutable behavior of this decorator.

class fireant.queries.builder.DimensionChoicesQueryBuilder(dataset, dimension)

Bases: fireant.queries.builder.QueryBuilder

This builder is used for building slicer queries for fetching the choices for a dimension given a set of filters.

fetch(hint=None, force_include=()) → pandas.core.series.Series

Fetch the data for this query and transform it into the widgets.

Parameters:

• hint – For database vendors that support it, add a query hint to collect analytics on the queries triggered by fireant.
• force_include – A list of dimension values to include in the result set. This can be used to avoid having necessary results cut off due to the pagination. These results will be returned at the head of the results.

Returns:

A list of dict (JSON) objects containing the widget configurations.

sql

Serializes this query builder as a set of SQL queries. This method will always return a list of one query since only one query is required to retrieve dimension choices.

The slicer query extends this with metrics, references, and totals.

class fireant.queries.builder.DimensionLatestQueryBuilder(dataset)

Bases: fireant.queries.builder.QueryBuilder

fetch(hint=None)

Fetches the data for this query instance and returns it in an instance of pd.DataFrame

Parameters:hint – For database vendors that support it, add a query hint to collect analytics on the queries triggerd by fireant.

sql

Serializes this query builder as a set of SQL queries. This method will always return a list of one query since only one query is required to retrieve dimension choices.

This function only handles dimensions (select+group by) and filtering (where/having), which is everything needed for the query to fetch choices for dimensions.

The slicer query extends this with metrics, references, and totals.

class fireant.queries.builder.QueryBuilder(dataset, table)

Bases: object

This is the base class for building slicer queries. This class provides an interface for building slicer queries via a set of functions which can be chained together.

fetch(hint=None)

Fetches the data for this query instance and returns it in an instance of pd.DataFrame

Parameters:hint – For database vendors that support it, add a query hint to collect analytics on the queries triggerd by fireant.

filter(*args, mutate=False, **kwargs)

Parameters:mutate – When True, overrides the immutable behavior of this decorator.

limit(*args, mutate=False, **kwargs)

Parameters:mutate – When True, overrides the immutable behavior of this decorator.

offset(*args, mutate=False, **kwargs)

Parameters:mutate – When True, overrides the immutable behavior of this decorator.

sql

Serialize this query builder object to a set of Pypika/SQL queries.

This is the base implementation shared by two implementations: the query to fetch data for a slicer request and the query to fetch choices for dimensions.

This function only handles dimensions (select+group by) and filtering (where/having), which is everything needed for the query to fetch choices for dimensions.

The slicer query extends this with metrics, references, and totals.

exception fireant.queries.builder.QueryException

Bases: fireant.exceptions.SlicerException

fireant.queries.builder.add_hints(queries, hint=None)

fireant.queries.builder.get_column_names(database, table)

fireant.queries.execution module

fireant.queries.execution.db_cache(func)

fireant.queries.execution.fetch_as_dataframe(query: str, database: fireant.database.base.Database)

Executes a query to fetch data from database middleware and builds/cleans the data as a data frame. The query execution is logged with its duration.

Parameters:

• database – instance of fireant.Database, database middleware
• query – Query string

Returns:

pd.DataFrame constructed from the result of the query

fireant.queries.execution.fetch_data(database: fireant.database.base.Database, queries: Union[collections.abc.Sized, Iterable], dimensions: Iterable[fireant.dataset.fields.Field], share_dimensions: Iterable[fireant.dataset.fields.Field] = (), reference_groups=())

fireant.queries.execution.log(func)

fireant.queries.execution.reduce_result_set(results: Iterable[pandas.core.frame.DataFrame], reference_groups, dimensions: Iterable[fireant.dataset.fields.Field], share_dimensions: Iterable[fireant.dataset.fields.Field])

Reduces the result sets from individual queries into a single data frame. This effectively joins sets of references and concatenates the sets of totals.

Parameters:

• results – A list of data frame
• reference_groups – A list of groups of references (grouped by interval such as WoW, etc)
• dimensions – A list of dimensions, used for setting the index on the result data frame.
• share_dimensions – A list of dimensions from which the totals are used for calculating share operations.

Returns:

fireant.queries.field_helper module

fireant.queries.field_helper.make_orders_for_dimensions(dimensions)

Creates a list of ordering for a slicer query based on a list of dimensions. The dimensions’s display definition is used preferably as the ordering term but the definition is used for dimensions that do not have a display definition.

Parameters:dimensions – Returns:a list of tuple pairs like (term, orientation) for ordering a SQL query where the first element is the term to order by and the second is the orientation of the ordering, ASC or DESC.

fireant.queries.field_helper.make_term_for_dimension(dimension, window=None)

Makes a list of pypika terms for a given slicer definition.

Parameters:

• dimension – A slicer dimension.
• window – A window function to apply to the dimension definition if it is a continuous dimension.

Returns:

a list of terms required to select and group by in a SQL query given a slicer dimension. This list will contain either one or two elements. A second element will be included if the dimension has a definition for its display field.

fireant.queries.field_helper.make_term_for_metrics(metric)

fireant.queries.finders module

exception fireant.queries.finders.CircularJoinsException

Bases: fireant.exceptions.SlicerException

exception fireant.queries.finders.MissingTableJoinException

Bases: fireant.exceptions.SlicerException

class fireant.queries.finders.ReferenceGroup(dimension, time_unit, intervals)

Bases: tuple

dimension

Alias for field number 0

intervals

Alias for field number 2

time_unit

Alias for field number 1

fireant.queries.finders.find_and_group_references_for_dimensions(dimensions, references)

Finds all of the references for dimensions and groups them by dimension, interval unit, number of intervals.

This structure reflects how the references need to be joined to the slicer query. References of the same type (WoW, WoW.delta, WoW.delta_percent) can share a join query.

Parameters:

• dimensions –
• references –

Returns:

An OrderedDict where the keys are 3-item tuples consisting of “Dimension, interval unit, # of intervals.

Example
{
    (Dimension(date_1), 'weeks', 1): [WoW, WoW.delta],
    (Dimension(date_1), 'years', 1): [YoY],
    (Dimension(date_7), 'days', 1): [DoD, DoD.delta_percent],
}

fireant.queries.finders.find_and_replace_reference_dimensions(references, dimensions)

Finds the dimension for a reference in the query if there is one and replaces it. This is to force the reference to use the same modifiers with a dimension if it is selected in the query.

Parameters:

• references –
• dimensions –

Returns:

fireant.queries.finders.find_filters_for_totals(filters)

Parameters:filters – Returns:a list of filters that should be applied to totals queries. This removes any filters from the list that have the OmitFromRollup modifier applied to them.

fireant.queries.finders.find_joins_for_tables(joins, base_table, required_tables)

Given a set of tables required for a slicer query, this function finds the joins required for the query and sorts them topologically.

Returns:A list of joins in the order that they must be joined to the query. Raises:MissingTableJoinException - If a table is required but there is no join for that table CircularJoinsException - If there is a circular dependency between two or more joins

fireant.queries.finders.find_metrics_for_widgets(widgets)

Returns:an ordered, distinct list of metrics used in all widgets as part of this query.

fireant.queries.finders.find_operations_for_widgets(widgets)

Returns:an ordered, distinct list of metrics used in all widgets as part of this query.

fireant.queries.finders.find_required_tables_to_join(elements, base_table)

Collect all the tables required for a given list of slicer elements. This looks through the definition and display_definition attributes of all elements and

This looks through the metrics, dimensions, and filter included in this slicer query. It also checks both the definition field of each element as well as the display definition for Unique Dimensions.

Returns:A collection of tables required to execute a query,

fireant.queries.finders.find_share_dimensions(dimensions, operations)

Returns a subset list of dimensions from the list of dimensions that are used as the over-dimension in share operations.

Parameters:

• dimensions –
• operations –

Returns:

fireant.queries.finders.find_totals_dimensions(dimensions, share_dimensions)

Parameters:

• dimensions –
• share_dimensions –

Returns:

an list of all dimension field in the list argument dimensions which have the Rollup modifier applied to them or are used as a basis for a share metric.

fireant.queries.pagination module

fireant.queries.pagination.paginate(data_frame, widgets, orders=(), limit=None, offset=None)

Parameters:

• data_frame – The result set to paginate.
• widgets – An iterable of widgets that the pagination is being applied for.
• orders – An iterable of (<Dimension/Metric>, pypika.Order)
• limit – A limit of the number of data points/series
• offset – A offset of the number of data points/series

Returns:

A paginated data frame. If the widget required grouped pagination, then there should be an upperbound limit*(n_index_level_0). Otherwise the data frame should have the same length as the limit.

fireant.queries.reference_helper module

fireant.queries.reference_helper.adapt_for_reference_query(reference_parts, database, dimensions, metrics, filters, references)

fireant.queries.slow_query_logger module

fireant.queries.special_cases module

fireant.queries.special_cases.adjust_dataframe_for_rolling_window(operations, data_frame)

This function adjusts the resulting data frame after executing a slicer query with a rolling operation. If there is a date dimension in the first level of the data frame’s index and a rolling operation is applied, it will slice the dates following the max window to remove it. This way, the adjustment of date filters applied in #adjust_daterange_filter_for_rolling_window are removed from the data frame but also in case there are no filters, the first few date data points will be removed where the rolling window cannot be calculated.

Parameters:

• operations –
• data_frame –

Returns:

fireant.queries.special_cases.adjust_daterange_filter_for_rolling_window(dimensions, operations, filters)

This function adjusts date filters for a rolling operation in order to select enough date to compute the values for within the original range.

It only applies when using a date dimension in the first position and a RangeFilter is used on that dimension. It is meant to be applied to a slicer query.

Parameters:

• dimensions – The dimensions applied to a slicer query
• operations – The dimensions used in widgets in a slicer query
• filters – The filters applied to a slicer query

Returns:

fireant.queries.special_cases.apply_operations_to_data_frame(operations, data_frame)

fireant.queries.special_cases.apply_special_cases(f)

fireant.queries.special_cases.apply_to_query_args(database, table, joins, dimensions, metrics, operations, filters, references, orders)

fireant.queries.sql_transformer module

fireant.queries.sql_transformer.make_latest_query(database: fireant.database.base.Database, base_table: pypika.queries.Table, joins: Iterable[fireant.dataset.joins.Join] = (), dimensions: Iterable[fireant.dataset.fields.Field] = ())

fireant.queries.sql_transformer.make_slicer_query(database: fireant.database.base.Database, base_table: pypika.queries.Table, joins: Iterable[fireant.dataset.joins.Join] = (), dimensions: Iterable[fireant.dataset.fields.Field] = (), metrics: Iterable[fireant.dataset.fields.Field] = (), filters: Iterable[fireant.dataset.filters.Filter] = (), orders: Iterable = ())

Creates a pypika/SQL query from a list of slicer elements.

This is the base implementation shared by two implementations: the query to fetch data for a slicer request and the query to fetch choices for dimensions.

This function only handles dimensions (select+group by) and filtering (where/having), which is everything needed for the query to fetch choices for dimensions.

The slicer query extends this with metrics, references, and totals.

Parameters:

• database –
• base_table – pypika.Table - The base table of the query, the one in the FROM clause
• joins – A collection of joins available in the slicer. This should include all slicer joins. Only joins required for the query will be used.
• dimensions – A collection of dimensions to use in the query.
• metrics – A collection of metrics to use in the query.
• filters – A collection of filters to apply to the query.
• orders – A collection of orders as tuples of the metric/dimension to order by and the direction to order in.

Returns:

fireant.queries.sql_transformer.make_slicer_query_with_totals_and_references(database, table, joins, dimensions, metrics, operations, filters, references, orders, share_dimensions=())

Parameters:

• database –
• table –
• joins –
• dimensions –
• metrics –
• operations –
• filters –
• references –
• orders –
• share_dimensions –

Returns:

fireant.queries.totals_helper module

fireant.queries.totals_helper.adapt_for_totals_query(totals_dimension, dimensions, filters)

Adapt filters for totals query. This function will select filters for total dimensions depending on the apply_filter_to_totals values for the filters. A total dimension with value None indicates the base query for which all filters will be applied by default.

Parameters:

• totals_dimension –
• dimensions –
• filters –

Returns: