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

Get a saved query by name: get_by_name()
Get a saved query by UUID: get_by_uuid()
Get a saved query by tags: get_by_tags()
Get all saved query tags: get_tags()
Get all saved queries: get()
Add a saved query: add()
Delete a saved query by name: delete_by_name()
Delete a saved query by UUID or SQ object: delete()

See also

Device assets axonius_api_client.api.assets.devices.Devices
User assets axonius_api_client.api.assets.users.Users

Parameters: parent (axonius_api_client.api.mixins.Model) –

property folders: FoldersQueries¶: Get the folders api for this object type.

update_folder(sq, folder, as_dataclass=False, create=True, echo=True)[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
folder (typing.Union[str, axonius_api_client.api.json_api.folders.queries.FolderModel]) –
create (bool) –
echo (bool) –

Returns

saved query dataclass or dict

Return type

t.Union[dict, models.SavedQuery]

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

t.Union[dict, models.SavedQuery]

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

t.Union[dict, models.SavedQuery]

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

t.Union[dict, models.SavedQuery]

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 (t.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

t.Union[dict, models.SavedQuery]

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 (t.Union[str, t.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

t.Union[dict, models.SavedQuery]

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

t.Union[dict, models.SavedQuery]

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

t.Union[dict, models.SavedQuery]

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 (t.Optional[t.Union[t.List[str], str]], optional) – fields
fields_manual (t.Optional[t.Union[t.List[str], str]], optional) – fields fully qualified
fields_regex (t.Optional[t.Union[t.List[str], str]], optional) – fields via regex
fields_fuzzy (t.Optional[t.Union[t.List[str], str]], optional) – fields via fuzzy
fields_default (bool, optional) – Include default fields
fields_root (t.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

t.Union[dict, models.SavedQuery]

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 (t.Optional[str]], optional) – previously generated query
expressions (t.Optional[t.List[str]], optional) – Expressions for GUI Query Wizard
wiz_entries (t.Optional[t.Union[str, t.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

t.Union[dict, models.SavedQuery]

copy(sq, name, private=False, asset_scope=False, as_dataclass=False, always_cached=False, folder=None, create=True, echo=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) –
folder (typing.Union[str, axonius_api_client.api.json_api.folders.queries.FolderModel, None]) –
create (bool) –
echo (bool) –

Returns

saved query dataclass or dict

Return type

t.Union[dict, models.SavedQuery]

get_by_multi(sq, as_dataclass=False, asset_scopes=False, cache=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) –
cache (bool) –

Returns

saved query dataclass or dict

Return type

t.Union[dict, models.SavedQuery]

Raises

ApiError – if sq is not a str, saved query dict, or saved query dataclass
models.SavedQueryNotFoundError – If no sq found with name or uuid from value

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

t.Union[dict, models.SavedQuery]

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

t.Union[dict, models.SavedQuery]

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 (t.Union[str, t.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

t.List[t.Union[dict, models.SavedQuery]]

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: t.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

t.Generator or: list of query event models

Return type

t.Union[t.Generator[QueryHistory, None, None], t.List[QueryHistory]]

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 (t.Optional[PatternLikeListy], optional) – Filter records run by users
run_from (t.Optional[PatternLikeListy], optional) – Filter records run from api/gui
tags (t.Optional[PatternLikeListy], optional) – Filter records by SQ tags
modules (t.Optional[PatternLikeListy], optional) – Filter records by asset type (defaults to parent asset type)
name_term (t.Optional[str], optional) – Filter records by SQ name pattern
date_start (t.Optional[datetime.datetime], optional) – Filter records after this date
date_end (t.Optional[datetime.datetime], optional) – Filter records before this date (will default to now if date_start supplied and no date_end)
sort_attribute (t.Optional[str], optional) – Sort records based on this attribute
sort_descending (bool, optional) – Sort records descending or ascending
search (t.Optional[str], optional) – AQL search value to filter records
filter (t.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 (t.Optional[int], optional) – Stop at row N
log_level (t.Union[int, str], optional) – log level to use for paging
run_by_values (t.Optional[t.List[str]], optional) – Output from get_query_history_run_by() (will be fetched if not supplied)
run_from_values (t.Optional[t.List[str]], optional) – Output from get_query_history_run_from() (will be fetched if not supplied)
request_obj (t.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

t.Generator[t.Union[dict, models.SavedQuery], None, None] –

if generator = True,: saved query dataclass or dict

Returns

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

Return type

t.List[t.Union[dict, models.SavedQuery]]

get_cached(**kwargs)[source]¶

Get all saved queries.

Examples

Get all saved queries

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

Parameters

generator – return an iterator

Yields

t.Generator[QueryHistory, None, None] –

if generator = True, saved query: dataclass or dict

Returns

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

Return type

t.List[t.Union[dict, models.SavedQuery]]

get_cached_single(value)[source]¶

Pass.

Parameters: value (typing.Union[str, dict, axonius_api_client.api.json_api.saved_queries.SavedQuery]) –
Return type: axonius_api_client.api.json_api.saved_queries.SavedQuery

property query_by_asset_type: str¶: Pass.

build_filter_query(query=None, add_query_by_asset_type=True)[source]¶

Pass.

Parameters

query (typing.Optional[str]) –
add_query_by_asset_type (bool) –

Return type

typing.Optional[str]

get_generator(folder_id='all', include_usage=True, get_view_data=True, as_dataclass=False, page_sleep=0, page_size=2000, row_start=0, row_stop=None, add_query_by_asset_type=True, log_level='debug', query=None, request_obj=None)[source]¶

Get Saved Queries using a generator.

Parameters

as_dataclass (bool, optional) – Return saved query dataclass instead of dict
folder_id (str) –
include_usage (bool) –
get_view_data (bool) –
page_sleep (int) –
page_size (int) –
row_start (int) –
row_stop (typing.Optional[int]) –
add_query_by_asset_type (bool) –
log_level (typing.Union[int, str]) –
query (typing.Optional[str]) –
request_obj (typing.Optional[axonius_api_client.api.json_api.saved_queries.SavedQueryGet]) –

Yields

t.Generator[QueryHistory, None, None] – saved query dataclass or dict

Return type

typing.Generator[axonius_api_client.api.json_api.saved_queries.QueryHistory, 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

t.Union[dict, models.SavedQuery]

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, folder=None, create=True, echo=True, **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 (t.Optional[t.Union[str, t.List[dict]]]) – API query wizard entries to parse into query and GUI query wizard expressions
tags (t.Optional[t.List[str]], optional) – list of tags
expressions (t.Optional[t.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) –
folder (typing.Union[str, axonius_api_client.api.json_api.folders.queries.FolderModel, None]) –
create (bool) –
echo (bool) –

Returns

saved query dataclass to create

Return type

models.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

t.Union[dict, models.SavedQuery]

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

Delete saved queries.

Parameters

rows (t.Union[t.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

t.List[t.Union[dict, models.SavedQuery]]

_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

t.Union[dict, models.SavedQuery]

_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

t.Union[dict, models.SavedQuery]

_update_from_dataclass(obj, uuid=None)[source]¶

Direct API method to update a saved query.

Parameters

obj (models.SavedQueryMixins) – pre-created dataclass
uuid (typing.Optional[str]) –

Returns

saved query dataclass

Return type

models.SavedQuery

_add_from_dataclass(obj)[source]¶

Direct API method to create a saved query.

Parameters: obj (models.SavedQueryCreate) – pre-created dataclass
Returns: saved query dataclass
Return type: models.SavedQuery

_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: Metadata

_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