4.4.5. Saved queries

API for working with saved queries for assets.

class axonius_api_client.api.assets.saved_query.SavedQuery(parent)[source]

Bases: ChildMixins

API object for working with saved queries for the parent asset type.

Examples

Create a client using axonius_api_client.connect.Connect and assume apiobj is either client.devices or client.users

>>> apiobj = client.devices  # or client.users
Parameters

parent (axonius_api_client.api.mixins.Model) –

update_name(sq, value, as_dataclass=False)[source]

Update the name of a Saved Query.

Parameters
  • sq (MULTI) – str with name or uuid, or saved query dict or dataclass

  • value (str) – new name

  • as_dataclass (bool, optional) – Return saved query dataclass instead of dict

Returns

saved query dataclass or dict

Return type

BOTH

update_description(sq, value, append=False, as_dataclass=False)[source]

Update the description of a Saved Query.

Parameters
  • sq (MULTI) – str with name or uuid, or saved query dict or dataclass

  • value (str) – description to set

  • append (bool, optional) – append to pre-existing description

  • as_dataclass (bool, optional) – Return saved query dataclass instead of dict

Returns

saved query dataclass or dict

Return type

BOTH

update_page_size(sq, value, as_dataclass=False)[source]

Update the GUI page size of a Saved Query.

Parameters
  • sq (MULTI) – str with name or uuid, or saved query dict or dataclass

  • value (int) – page size to set

  • as_dataclass (bool, optional) – Return saved query dataclass instead of dict

Returns

saved query dataclass or dict

Return type

BOTH

update_sort(sq, field=None, descending=True, as_dataclass=False)[source]

Update the sort of a Saved Query.

Parameters
  • sq (MULTI) – str with name or uuid, or saved query dict or dataclass

  • field (Optional[str], optional) – field to sort results on

  • descending (bool, optional) – sort descending or ascending

  • as_dataclass (bool, optional) – Return saved query dataclass instead of dict

Returns

saved query dataclass or dict

Return type

BOTH

update_tags(sq, value, remove=False, append=False, as_dataclass=False)[source]

Update the tags of a Saved Query.

Parameters
  • sq (MULTI) – str with name or uuid, or saved query dict or dataclass

  • value (Union[str, List[str]]) – tags to set

  • remove (bool, optional) – remove tags in value from saved query tags

  • append (bool, optional) – append tags in value to pre-existing saved query tags

  • as_dataclass (bool, optional) – Return saved query dataclass instead of dict

Returns

saved query dataclass or dict

Return type

BOTH

update_always_cached(sq, value, as_dataclass=False)[source]

Update the always_cached flag of a Saved Query.

Parameters
  • sq (MULTI) – str with name or uuid, or saved query dict or dataclass

  • value (bool) – should the saved query always being cached

  • as_dataclass (bool, optional) – Return saved query dataclass instead of dict

Returns

saved query dataclass or dict

Return type

BOTH

update_private(sq, value, as_dataclass=False)[source]

Update the private flag of a Saved Query.

Parameters
  • sq (MULTI) – str with name or uuid, or saved query dict or dataclass

  • value (bool) – should the saved query be private

  • as_dataclass (bool, optional) – Return saved query dataclass instead of dict

Returns

saved query dataclass or dict

Return type

BOTH

update_fields(sq, fields=None, fields_manual=None, fields_regex=None, fields_regex_root_only=True, fields_fuzzy=None, fields_default=False, fields_root=None, remove=False, append=False, as_dataclass=False)[source]

Update the tags of a Saved Query.

Parameters
  • sq (MULTI) – str with name or uuid, or saved query dict or dataclass

  • fields (Optional[Union[List[str], str]], optional) – fields

  • fields_manual (Optional[Union[List[str], str]], optional) – fields fully qualified

  • fields_regex (Optional[Union[List[str], str]], optional) – fields via regex

  • fields_fuzzy (Optional[Union[List[str], str]], optional) – fields via fuzzy

  • fields_default (bool, optional) – Include default fields

  • fields_root (Optional[str], optional) – fields via root

  • remove (bool, optional) – remove supplied fields from saved query fields

  • append (bool, optional) – append supplied fields in value to pre-existing saved query fields

  • as_dataclass (bool, optional) – Return saved query dataclass instead of dict

  • fields_regex_root_only (bool) –

Returns

saved query dataclass or dict

Return type

BOTH

update_query(sq, query=None, expressions=None, wiz_entries=None, append=False, append_and_flag=False, append_not_flag=False, as_dataclass=False, **kwargs)[source]

Update the query of a Saved Query.

Parameters
  • sq (MULTI) – str with name or uuid, or saved query dict or dataclass

  • query (Optional[str]], optional) – previously generated query

  • expressions (Optional[List[str]], optional) – Expressions for GUI Query Wizard

  • wiz_entries (Optional[Union[str, List[dict]]]) – API query wizard entries to parse into query and GUI query wizard expressions

  • append (bool, optional) – append query to pre-existing query

  • append_and_flag (bool, optional) – use and instead of or for appending query

  • append_not_flag (bool, optional) – use ‘and not’/’or not’ for appending query

  • as_dataclass (bool, optional) – Return saved query dataclass instead of dict

Returns

saved query dataclass or dict

Return type

BOTH

copy(sq, name, private=False, asset_scope=False, always_cached=False, as_dataclass=False)[source]

Create a copy of a Saved Query.

Parameters
  • sq (MULTI) – str with name or uuid, or saved query dict or dataclass

  • name (str) – name to use for new sq

  • private (bool, optional) – Set new sq as private

  • asset_scope (bool, optional) – Set new sq as asset scope query

  • as_dataclass (bool, optional) – Return saved query dataclass instead of dict

  • always_cached (bool) –

Returns

saved query dataclass or dict

Return type

BOTH

get_by_multi(sq, as_dataclass=False, asset_scopes=False, **kwargs)[source]

Get a saved query by name or uuid.

Parameters
  • sq (MULTI) – str with name or uuid, or saved query dict or dataclass

  • as_dataclass (bool, optional) – Return saved query dataclass instead of dict

  • **kwargs – passed to get()

  • asset_scopes (bool) –

Returns

saved query dataclass or dict

Return type

BOTH

Raises
get_by_name(value, as_dataclass=False, **kwargs)[source]

Get a saved query by name.

Examples

Get a saved query by name

>>> sq = apiobj.saved_query.get_by_name(name="test")
>>> sq['tags']
['Unmanaged Devices']
>>> sq['description'][:80]
'Devices that have been seen by at least one agent or at least one endpoint manag'
>>> sq['view']['fields']
[
    'adapters',
    'specific_data.data.name',
    'specific_data.data.hostname',
    'specific_data.data.last_seen',
    'specific_data.data.network_interfaces.manufacturer',
    'specific_data.data.network_interfaces.mac',
    'specific_data.data.network_interfaces.ips',
    'specific_data.data.os.type',
    'labels'
]
>>> sq['view']['query']['filter'][:80]
'(specific_data.data.adapter_properties == "Agent") or (specific_data.data.adapte'
Parameters
  • value (str) – name of saved query

  • as_dataclass (bool, optional) – Return saved query dataclass instead of dict

Raises

SavedQueryNotFoundError – if no saved query found with name of value

Returns

saved query dataclass or dict

Return type

BOTH

get_by_uuid(value, as_dataclass=False, **kwargs)[source]

Get a saved query by uuid.

Examples

Get a saved query by uuid

>>> sq = apiobj.saved_query.get_by_uuid(value="5f76721ce4557d5cba93f59e")
Parameters
  • value (str) – uuid of saved query

  • as_dataclass (bool, optional) – Return saved query dataclass instead of dict

Raises

SavedQueryNotFoundError – if no saved query found with uuid of value

Returns

saved query dataclass or dict

Return type

BOTH

get_by_tags(value, as_dataclass=False, **kwargs)[source]

Get saved queries by tags.

Examples

Get all saved queries with tagged with ‘AD’

>>> sqs = apiobj.saved_query.get_by_tags('AD')
>>> len(sqs)
2

Get all saved queries with tagged with ‘AD’ or ‘AWS’

>>> sqs = apiobj.saved_query.get_by_tags(['AD', 'AWS'])
>>> len(sqs)
5
Parameters
  • value (Union[str, List[str]]) – list of tags

  • as_dataclass (bool, optional) – Return saved query dataclass instead of dict

Raises

SavedQueryTagsNotFoundError – if no saved queries found with supplied tags

Returns

list of saved query dataclass or dict containing any tags in value

Return type

List[BOTH]

get_tags_slow()[source]

Get all tags for saved queries.

Examples

Get all known tags for all saved queries

>>> tags = apiobj.saved_query.get_tags()
>>> len(tags)
19
Returns

list of all tags in use

Return type

List[str]

get_tags()[source]

Get all tags for saved queries.

Return type

typing.List[str]

get_query_history_run_by()[source]

Get the valid values for the run_by attribute for getting query history.

Return type

typing.List[str]

get_query_history_run_from()[source]

Get the valid values for the run_from attribute for getting query history.

Return type

typing.List[str]

get_query_history(generator=False, **kwargs)[source]

Get query history.

Parameters
  • generator (bool, optional) – Return a generator or a list

  • **kwargs – passed to get_fetch_history_generator()

Returns

Generator or list of query event models

Return type

Union[HIST_GEN, HIST_LIST]

get_query_history_generator(run_by=None, run_from=None, tags=None, modules=None, name_term=None, date_start=None, date_end=None, sort_attribute=None, sort_descending=False, search=None, filter=None, page_sleep=0, page_size=2000, row_start=0, row_stop=None, log_level='debug', run_by_values=None, run_from_values=None, request_obj=None)[source]

Get query history.

Parameters
  • run_by (OPT_STR_RE_LISTY, optional) – Filter records run by users

  • run_from (OPT_STR_RE_LISTY, optional) – Filter records run from api/gui

  • tags (OPT_STR_RE_LISTY, optional) – Filter records by SQ tags

  • modules (OPT_STR_RE_LISTY, optional) – Filter records by asset type (defaults to parent asset type)

  • name_term (Optional[str], optional) – Filter records by SQ name pattern

  • date_start (Optional[datetime.datetime], optional) – Filter records after this date

  • date_end (Optional[datetime.datetime], optional) – Filter records before this date (will default to now if date_start supplied and no date_end)

  • sort_attribute (Optional[str], optional) – Sort records based on this attribute

  • sort_descending (bool, optional) – Sort records descending or ascending

  • search (Optional[str], optional) – AQL search value to filter records

  • filter (Optional[str], optional) – AQL to filter records

  • page_sleep (int, optional) – Sleep N seconds between pages

  • page_size (int, optional) – Get N records per page

  • row_start (int, optional) – Start at row N

  • row_stop (Optional[int], optional) – Stop at row N

  • log_level (Union[int, str], optional) – log level to use for paging

  • run_by_values (Optional[List[str]], optional) – Output from get_query_history_run_by() (will be fetched if not supplied)

  • run_from_values (Optional[List[str]], optional) – Output from get_query_history_run_from() (will be fetched if not supplied)

  • request_obj (Optional[QueryHistoryRequest], optional) – Request object to use for options

Return type

typing.List[axonius_api_client.api.json_api.saved_queries.QueryHistory]

get(generator=False, **kwargs)[source]

Get all saved queries.

Examples

Get all saved queries

>>> sqs = apiobj.saved_query.get()
>>> len(sqs)
39
Parameters

generator (bool) – return an iterator

Yields

GEN – if generator = True, saved query dataclass or dict

Returns

if generator = False, list of saved query dataclass or dict

Return type

List[BOTH]

get_generator(folder=None, include_usage=False, get_view_data=True, creators=None, used_in=None, as_dataclass=False, page_sleep=0, page_size=2000, row_start=0, row_stop=None, log_level='debug')[source]

Get Saved Queries using a generator.

Parameters
Yields

GEN – saved query dataclass or dict

Return type

typing.Generator[typing.Union[dict, axonius_api_client.api.json_api.saved_queries.SavedQuery], None, None]

add(as_dataclass=False, **kwargs)[source]

Create a saved query.

Examples

Create a saved query using a axonius_api_client.api.wizards.wizard.Wizard

>>> parsed = apiobj.wizard_text.parse(content="simple hostname contains blah")
>>> query = parsed["query"]
>>> expressions = parsed["expressions"]
>>> sq = apiobj.saved_query.add(
...     name="test",
...     query=query,
...     expressions=expressions,
...     description="meep meep",
...     tags=["nyuck1", "nyuck2", "nyuck3"],
... )

Notes

Saved Queries created without expressions will not be editable using the query wizard in the GUI. Use axonius_api_client.api.wizards.wizard.Wizard to produce a query and it’s accordant expressions for the GUI query wizard.

Parameters
  • as_dataclass (bool, optional) – return saved query dataclass or dict

  • **kwargs – passed to build_add_model()

Returns

saved query dataclass or dict

Return type

BOTH

build_add_model(name, query=None, wiz_entries=None, tags=None, description=None, expressions=None, fields=None, fields_manual=None, fields_regex=None, fields_regex_root_only=True, fields_fuzzy=None, fields_default=True, fields_root=None, sort_field=None, sort_descending=True, column_filters=None, gui_page_size=None, private=False, always_cached=False, asset_scope=False, **kwargs)[source]

Create a saved query.

Examples

Create a saved query using a axonius_api_client.api.wizards.wizard.Wizard

>>> parsed = apiobj.wizard_text.parse(content="simple hostname contains blah")
>>> query = parsed["query"]
>>> expressions = parsed["expressions"]
>>> sq = apiobj.saved_query.add(
...     name="test",
...     query=query,
...     expressions=expressions,
...     description="meep meep",
...     tags=["nyuck1", "nyuck2", "nyuck3"],
... )

Notes

Saved Queries created without expressions will not be editable using the query wizard in the GUI. Use axonius_api_client.api.wizards.wizard.Wizard to produce a query and it’s accordant expressions for the GUI query wizard.

Parameters
  • name (str) – name of saved query

  • query (typing.Optional[str]) – query built by GUI or API query wizard

  • wiz_entries (Optional[Union[str, List[dict]]]) – API query wizard entries to parse into query and GUI query wizard expressions

  • tags (Optional[List[str]], optional) – list of tags

  • expressions (Optional[List[str]], optional) – Expressions for GUI Query Wizard

  • fields (typing.Union[typing.List[str], str, None]) – fields to return for each asset (will be validated)

  • fields_manual (typing.Union[typing.List[str], str, None]) – fields to return for each asset (will NOT be validated)

  • fields_regex (typing.Union[typing.List[str], str, None]) – regex of fields to return for each asset

  • fields_fuzzy (typing.Union[typing.List[str], str, None]) – string to fuzzy match of fields to return for each asset

  • fields_default (bool) – include the default fields defined in the parent asset object

  • fields_root (typing.Optional[str]) – include all fields of an adapter that are not complex sub-fields

  • sort_field (typing.Optional[str]) – sort the returned assets on a given field

  • sort_descending (bool) – reverse the sort of the returned assets

  • column_filters (typing.Optional[dict]) – NOT_SUPPORTED

  • gui_page_size (typing.Optional[int]) – show N rows per page in GUI

  • private (bool) – make this saved query private to current user

  • always_cached (bool) – always keep this query cached

  • asset_scope (bool) – make this query an asset scope query

  • description (typing.Optional[str]) –

  • fields_regex_root_only (bool) –

Returns

saved query dataclass to create

Return type

json_api.saved_queries.SavedQueryCreate

delete_by_name(value, as_dataclass=False)[source]

Delete a saved query by name.

Examples

Delete the saved query by name

>>> deleted = apiobj.saved_query.delete_by_name(name="test")
Parameters
  • value (str) – name of saved query to delete

  • as_dataclass (bool, optional) – Return saved query dataclass instead of dict

Returns

saved query dataclass or dict

Return type

BOTH

delete(rows, errors=True, refetch=True, as_dataclass=False, **kwargs)[source]

Delete saved queries.

Parameters
  • rows (Union[List[MULTI], MULTI]) – str or list of str with name, str or list of str with uuid, saved query dict or list of dict, or saved query dataclass or list of dataclass

  • errors (bool, optional) – Raise errors if SQ not found or other error

  • refetch (bool, optional) – refetch dataclass objects before deleting SQ

  • as_dataclass (bool, optional) – Return saved query dataclass instead of dict

Returns

list of saved query dataclass or dict that were deleted

Return type

List[BOTH]

_update_flag(attr, sq, value, as_dataclass=False)[source]

Update a boolean flag for a SQ.

Parameters
  • attr (str) – attribute name

  • sq (MULTI) – saved query to update

  • value (bool) – value to set to attr

  • as_dataclass (bool, optional) – Return saved query dataclass instead of dict

Returns

saved query dataclass or dict

Return type

BOTH

_update_handler(sq, as_dataclass=False)[source]

Update a SQ.

Parameters
  • sq (MULTI) – saved query to update

  • as_dataclass (bool, optional) – Return saved query dataclass instead of dict

Returns

saved query dataclass or dict

Return type

BOTH

_update_from_dataclass(obj, uuid)[source]

Direct API method to update a saved query.

Parameters
  • obj (json_api.saved_queries.SavedQueryCreate) – pre-created dataclass

  • uuid (str) –

Returns

saved query dataclass

Return type

MODEL

_update(uuid, name, view, description='', tags=None, private=False, always_cached=False, asset_scope=False)[source]

Direct API method to update a saved query.

Parameters
  • uuid (str) – UUID of SQ to update

  • name (str) – name to set

  • view (dict) – view object to set

  • description (str, optional) – description to set

  • tags (Optional[List[str]], optional) – tags to set

  • private (bool, optional) – set sq as private or public

  • always_cached (bool, optional) – set sq as always cached

  • asset_scope (bool, optional) – set sq as asset scope query

Returns

saved query dataclass

Return type

MODEL

_add_from_dataclass(obj)[source]

Direct API method to create a saved query.

Parameters

obj (json_api.saved_queries.SavedQueryCreate) – pre-created dataclass

Returns

saved query dataclass

Return type

MODEL

_add(name, view, description='', tags=None, private=False, always_cached=False, asset_scope=False)[source]

Direct API method to create a saved query.

Parameters
  • name (str) – name to set

  • view (dict) – view object to set

  • description (str, optional) – description to set

  • tags (Optional[List[str]], optional) – tags to set

  • private (bool, optional) – set sq as private or public

  • always_cached (bool, optional) – set sq as always cached

  • asset_scope (bool, optional) – set sq as asset scope query

Returns

saved query dataclass

Return type

MODEL

_delete(uuid)[source]

Direct API method to delete saved queries.

Parameters

uuid (str) – uuid of SQ to delete

Returns

Metadata object containing UUID of deleted SQ

Return type

json_api.generic.Metadata

_get(limit=2000, offset=0, sort=None, filter=None, search='', folder_id='', creator_ids=None, used_in=None, get_view_data=True, include_usage=False)[source]

Direct API method to get all saved queries.

Parameters
Returns

list of saved query dataclass

Return type

List[MODEL]

_get_model(request_obj)[source]

Direct API method to get all saved queries.

Parameters

request_obj (axonius_api_client.api.json_api.saved_queries.SavedQueryGet) –

Return type

typing.List[axonius_api_client.api.json_api.saved_queries.SavedQuery]

_check_name_exists(value)[source]

Check if a SQ already exists with a given name.

Parameters

value (str) – Name to check

Raises

AlreadyExists – if SQ with name of value found

_get_query_history(request_obj=None)[source]

Pass.

Parameters

request_obj (typing.Optional[axonius_api_client.api.json_api.saved_queries.QueryHistoryRequest]) –

Return type

typing.List[axonius_api_client.api.json_api.saved_queries.QueryHistory]

_get_query_history_run_by()[source]

Get the valid values for the run_by attribute for getting query history.

Return type

axonius_api_client.api.json_api.generic.ListValueSchema

_get_query_history_run_from()[source]

Get the valid values for the run_from attribute for getting query history.

Return type

axonius_api_client.api.json_api.generic.ListValueSchema

_get_tags()[source]

Get the valid tags.

Return type

axonius_api_client.api.json_api.generic.ListValueSchema

__init__(parent)

Mixins model for API child objects.

Parameters

parent (axonius_api_client.api.mixins.Model) – parent API model of this child

__repr__()

Show info for this model object.

Return type

str

__str__()

Show info for this model object.

Return type

str

_init(parent)

Post init method for subclasses to use for extra setup.

Parameters

parent (axonius_api_client.api.mixins.Model) – parent API model of this child