Search ¶

Table of Contents

Search
- Client

Client ¶

class Search.Client¶

A client object representing ‘Search’ Service:

import almdrlib

client = almdrlib.client('search')

Available methods:

complete_search()
get_all_pending_searches()
get_em_grammar()
get_peg_grammar()
get_query_results()
get_search_results()
get_search_status()
read_messages()
read_messages_get()
release_search()
rerun_search()
start_query_execution()
validate_search()

complete_search(**kwargs)¶

Run a suspended interactive search to completion

Request Syntax

response = client.complete_search(
    account_id='string'
    search_uuid='string'
    x_invoked_by='string'
)

Parameters

account_id (string) –
[REQUIRED]

The AIMS account ID
search_uuid (uuid) –
[REQUIRED]

A search UUID
x_invoked_by (string) –
A one or two-word description of your client

Default: openapi-client

Returns: None

get_all_pending_searches(**kwargs)¶

Get all pending searches across all accounts

Request Syntax

response = client.get_all_pending_searches(
    x_invoked_by='string'
)

Parameters

x_invoked_by (string) –

A one or two-word description of your client

Default: openapi-client

Return type

list

Returns

Response Syntax

[
    {
        'account_id': 'None',
        'authoritative_retry': 'string',
        'details': 'None',
        'external_details': 'None',
        'jobs_count': 'number',
        'progress': 'None',
        'raw_request': 'string',
        'rerun': 'None',
        'retried_by': [
            'None'
        ],
        'search_end': 'None',
        'search_start': 'None',
        'search_status': 'None',
        'search_uuid': 'None',
        'search_version': '1'|'2',
        'status_details': 'None',
        'total_found': 'number'
    }
]

Response Definitions

(dict) –

A summary of a search that gives just the essential details

account_id (dict) –

authoritative_retry (string) –

The UUID of the first successful search that was a retry of this search. This field is only populated when search_status is or was failed. If this field is populated, its value will always be in retried_by.

details (dict) –

external_details (dict) –

jobs_count (number) –

The number of filter jobs required to run this search.

progress (dict) –

raw_request (string) –

The raw request received by the search service.

rerun (dict) –

retried_by (list) –

A list of search UUIDs of searches that are retries of this search, in the order the retries were launched. This field is only populated after a search fails (i.e. the search_status is or was failed).

(dict) –

search_end (dict) –

search_start (dict) –

search_status (dict) –

search_uuid (dict) –

search_version (number) –

The search version requested.

Valid values: 1, 2

status_details (dict) –

total_found (number) –

The number of results found in the search.

get_em_grammar(**kwargs)¶

Get the SQL grammar used by Expert Mode Search

The grammar has three categories that will be in the result:

aggregator
- functions like MIN, MAX, and COUNT.
projector
- functions like GEOIP, FROM_EPOCHTIME, and NOW.
structure
- keywords like SELECT, FROM, and AS.

Each of these will have an object as value, where “keywords” is the only key coming out of the backend (more will be added by the UI). The value for “keywords” is one big map with all the keywords and their specs.

This API is used internally to the search project and is subject to change without notice to customers.

Request Syntax

response = client.get_em_grammar(
    x_invoked_by='string'
)

Parameters

x_invoked_by (string) –

A one or two-word description of your client

Default: openapi-client

Return type

dict

Returns

Response Syntax

{
    'aggregator': {
        'keywords': {
            '(variable)': {
                'spec': [
                    {
                        'help': 'string',
                        'insertText': 'string',
                        'label': 'string'
                    }
                ]
            }
        }
    },
    'projector': {
        'keywords': {
            '(variable)': {
                'spec': [
                    {
                        'help': 'string',
                        'insertText': 'string',
                        'label': 'string'
                    }
                ]
            }
        }
    },
    'structure': {
        'keywords': {
            '(variable)': {
                'spec': [
                    {
                        'help': 'string',
                        'insertText': 'string',
                        'label': 'string'
                    }
                ]
            }
        }
    }
}

Response Definitions

aggregator (dict) –

keywords (dict) –

(variable) (dict) –

A subcomponent of the grammar

spec (list) –

(dict) –

A definition of a function in the grammar

help (string) –

insertText (string) –

label (string) –

projector (dict) –

keywords (dict) –

(variable) (dict) –

A subcomponent of the grammar

spec (list) –

(dict) –

A definition of a function in the grammar

help (string) –

insertText (string) –

label (string) –

structure (dict) –

keywords (dict) –

(variable) (dict) –

A subcomponent of the grammar

spec (list) –

(dict) –

A definition of a function in the grammar

help (string) –

insertText (string) –

label (string) –

get_peg_grammar(**kwargs)¶

Get the PEG grammar for the AL SQL language

This API is used internally to the search project and is subject to change without notice to customers.

Request Syntax

response = client.get_peg_grammar(
    x_invoked_by='string'
)

Parameters

x_invoked_by (string) –

A one or two-word description of your client

Default: openapi-client

Return type

string

Returns

Response Syntax

'string'

Response Definitions

get_query_results(**kwargs)¶

Returns the results of a query execution specified by query_execution_id. This is deprecated in favor of the get_search_results operation which has a better definition. The two are functionally equivalent.

Request Syntax

response = client.get_query_results(
    account_id='string'
    details='False|True'
    limit='integer'
    offset='integer'
    query_execution_id='string'
    starting_token='string'
)

Parameters

account_id (string) –
[REQUIRED]

The AIMS account ID
details (boolean) –
Return search execution details

Valid values: True, False

Default: False
limit (integer) –
Limit the number of elements in the response

Default: 100
offset (integer) – offset within a set of results
query_execution_id (string) – [REQUIRED]
starting_token (string) – A next_token from a previous request to continue paging results

Returns: None

get_search_results(**kwargs)¶

Get the paginated results of a search.

Request Syntax

response = client.get_search_results(
    account_id='string'
    details='False|True'
    limit='number'
    offset='number'
    search_uuid='string'
    selected=[
        'number'
    ]
    starting_token='string'
    x_invoked_by='string'
)

Parameters

account_id (string) –
[REQUIRED]

The AIMS account ID
details (boolean) –
Return debugging details of the search

Default: False
limit (number) –
Limit the number of elements in the response

Default: 100
offset (number) – Offset with the results (used in conjunction with limit)
search_uuid (uuid) –
[REQUIRED]

A search UUID
selected (list) –

Get just a list of result rows numbers, constrained by the limit and offset parameters. This should be a comma-separated list of row numbers. The length of the list is limited by the general requirements for the size of the GET request (2048 bytes, including URL). The list should be URL encoded. If the requested row does not belong to the already found rows then it’ll not be returned. E.g. “2,5,29,31,45,99,100”
- (number) –
starting_token (string) – A next_token from a previous response to continue paging results
x_invoked_by (string) –
A one or two-word description of your client

Default: openapi-client

Return type

dict

Returns

Response Syntax

'dict'

Response Definitions

get_search_status(**kwargs)¶

Get the status of a search

Request Syntax

response = client.get_search_status(
    account_id='string'
    search_uuid='string'
    x_invoked_by='string'
)

Parameters

account_id (string) –
[REQUIRED]

The AIMS account ID
search_uuid (uuid) –
[REQUIRED]

A search UUID
x_invoked_by (string) –
A one or two-word description of your client

Default: openapi-client

Return type

dict

Returns

Response Syntax

{
    'account_id': 'string',
    'authoritative_retry': 'string',
    'details': {
        'cost': {
            'total': 'number'
        },
        'request': 'string',
        'requested_type': 'string',
        'search_type': 'string',
        'stats': {},
        'submit_ts': 'number',
        'update_ts': 'number'
    },
    'external_details': 'string',
    'progress': 'number',
    'rerun': {
        'retried_by': 'string',
        'retry': 'False|True'
    },
    'retried_by': [
        'string'
    ],
    'search_end': 'number',
    'search_start': 'number',
    'search_status': 'pending'|'failed'|'suspended'|'complete'|'released',
    'search_uuid': 'string',
    'status_details': 'string',
    'total_found': 'number'
}

Response Definitions

account_id (string) –

The AIMS Account ID

authoritative_retry (string) –

The UUID of the first successful search that was a retry of this search. This field is only populated when search_status is or was failed. If this field is populated, its value will always be in retried_by.

details (dict) – [REQUIRED]

cost (dict) – [REQUIRED]

A map containing the costs of various components of the search, if you have permission to view such data.

total (number) –

The total cost of the search.

request (string) –

The SQL query that was submitted for the search.

requested_type (dict) –

The type of the search that was requested. This may also be “unknown” for v1 searches which have been wrapped to be v2 searches.

search_type (dict) –

The type of the search. This may also be “unknown” for v1 searches which have been wrapped to be v2 searches.

stats (dict) –

Internal statistics of the search.

submit_ts (number) –

An epoch timestamp of when the search was submitted. This is also the value of NOW() in the search.

update_ts (number) –

An epoch timestamp of when the search was last updated.

external_details (string) –

An external-facing description that gives more details to the search_status field.

progress (number) –

An estimate of the progress of the search completion on a scale of 0-100.

rerun (dict) – [REQUIRED]

An object describing the search this search is a rerun of.

retried_by (uuid) –

A unique identifier for a search

retry (boolean) –

If true, this search is a retry of the search in retried_by because that search failed.

retried_by (list) –

A list of search UUIDs of searches that are retries of this search, in the order the retries were launched. This field is only populated after a search fails (i.e. the search_status is or was failed).

(uuid) –

A unique identifier for a search

search_end (number) –

Unix timestamp of requested search timeframe end

search_start (number) –

Unix timestamp of requested search timeframe beginning

search_status (string) –

The state of the search.

pending is running

suspended is a search that has partially run but is no longer executing

failed is a search that encountered an error

complete is a search that completed successfully

released is a search that has been stopped and/or had its results deleted.

Valid values: pending, failed, suspended, complete, released

search_uuid (uuid) –

A unique identifier for a search

status_details (string) –

An internal-facing description of the search_status field, typically used for failed searches.

total_found (number) –

The number of results found in the search.

read_messages(**kwargs)¶

Read a set of messages from storage by ID

Request Syntax

response = client.read_messages(
    account_id='string'
    datatype='logmsgs'
    fields='string'
    ids=[
        'string'
    ]
    properties='False|True'
    tokens_offsets='False|True'
)

Parameters

account_id (string) –
[REQUIRED]

The AIMS account ID
datatype (string) –
[REQUIRED]

Valid values: logmsgs
fields (string) – List of comma-separated fields names in messages.
ids (list) –
[REQUIRED]

List of Base64 encoded AMI4 or NSM message IDs. Both Message ID types can be used in the same request.
- (string) –
properties (boolean) – Default: False
tokens_offsets (boolean) –
Optional parameter for requesting tokens offsets in parsing results.

Default: False

Return type

list

Returns

Response Syntax

[
    {
        'error': {},
        'fields': {},
        'id': {
            'account': 'integer',
            'aid': 'integer',
            'msgid': 'string'
        }
    }
]

Response Definitions

(dict) –

error (dict) –

fields (dict) –

id (dict) –

account (integer) –

aid (integer) –

msgid (string) –

read_messages_get(**kwargs)¶

Read a set of messages from storage by ID

Request Syntax

response = client.read_messages_get(
    account_id='string'
    datatype='logmsgs'
    fields='string'
    ids=[
        'string'
    ]
    properties='False|True'
    tokens_offsets='False|True'
)

Parameters

account_id (string) –
[REQUIRED]

The AIMS account ID
datatype (string) –
[REQUIRED]

Valid values: logmsgs
fields (string) – List of comma-separated fields names in messages.
ids (list) –
[REQUIRED]

Comma-separated list of Base64 encoded AMI4 or NSM message IDs. Both Message ID types can be used in the same request.
- (string) –
properties (boolean) –
Request properties in parsing results.

Default: False
tokens_offsets (boolean) –
Request tokens offsets in parsing results.

Default: False

Return type

list

Returns

Response Syntax

[
    {
        'error': {},
        'fields': {},
        'id': {
            'account': 'integer',
            'aid': 'integer',
            'msgid': 'string'
        }
    }
]

Response Definitions

(dict) –

error (dict) –

fields (dict) –

id (dict) –

account (integer) –

aid (integer) –

msgid (string) –

release_search(**kwargs)¶

Stops an ongoing search if it is currently running. Deletes the search results if any exist, regardless of the current search state.

Request Syntax

response = client.release_search(
    account_id='string'
    search_uuid='string'
    x_invoked_by='string'
)

Parameters

account_id (string) –
[REQUIRED]

The AIMS account ID
search_uuid (uuid) –
[REQUIRED]

A search UUID
x_invoked_by (string) –
A one or two-word description of your client

Default: openapi-client

Returns: None

rerun_search(**kwargs)¶

Reruns the specified search if it is allowed

Request Syntax

response = client.rerun_search(
    account_id='string'
    redefine_now='False|True'
    retry='False|True'
    search_uuid='string'
    x_invoked_by='string'
)

Parameters

account_id (string) –
[REQUIRED]

The AIMS account ID
redefine_now (boolean) –
When retry is false, you can choose to redefine the value of NOW() to the time this API is called. If the original search used the timeframe query string parameter, the start and end time will be recalculated accordingly.

Default: False
retry (boolean) –
Whether to link the given search to the new search in the retried_by field of the original search (true) or simply copy the search and rerun it (false). Defaults to false.

Default: False
search_uuid (uuid) –
[REQUIRED]

A search UUID
x_invoked_by (string) –
A one or two-word description of your client

Default: openapi-client

Returns: None

start_query_execution(**kwargs)¶

Request the execution of a new search. Accepts either SQL or JSON form of search request. Details on how the SQL statements look will be given in a separate document.

Request Syntax

response = client.start_query_execution(
    account_id='string'
    end='integer'
    execution_mode='shared'|'ecs'
    query_string='string'
    search_type='auto'|'batch'|'report'
    start='integer'
    timeframe='integer'
    x_invoked_by='string'
)

Parameters

account_id (string) –
[REQUIRED]

The AIMS account ID
end (integer) – Option to specify the end of search query time frame. This must be used with end parameter. If start, end or timeframe are used in conjunction with a search query that has exact timeframe conditions, the URL query parameters are ignored. This parameter is mutually exclusive with timeframe.
execution_mode (string) –
The execution_mode describes how the user would like the search to execute (using Lambda and/or ECS).
- shared will force a search to execute using both Lambda and ECS resources.
- ecs will force a search to execute using only ECS resources.
Valid values: shared, ecs

Default: shared
query_string (string) –
search_type (string) –
The requested_search_type describes how the user would like the search to execute. See the SearchType model for more information.
- auto as a requested search type will pick either the interactive or batch search type, depending on whether the query has (batch) or does not have (interactive) aggregation.
- batch will force a search to execute as a batch search.
- report will force a search to execute as a report search.
See the SearchType model for more information.

Valid values: auto, batch, report

Default: auto
start (integer) – Option to specify the start of search query time frame. This must be used with end parameter. If start, end or timeframe are used in conjunction with a search query that has exact timeframe conditions, the URL query parameters are ignored. This parameter is mutually exclusive with timeframe.
timeframe (integer) – Option to specify the search time frame duration in past seconds. If start, end or timeframe are used in conjunction with a search query that has exact timeframe conditions, the URL query parameters are ignored. This parameter is mutually exclusive with start and end.
x_invoked_by (string) –
A one or two-word description of your client

Default: openapi-client

Return type

dict

Returns

Response Syntax

{
    'account_id': 'string',
    'authoritative_retry': 'string',
    'details': {
        'cost': {
            'total': 'number'
        },
        'request': 'string',
        'requested_type': 'string',
        'search_type': 'string',
        'stats': {},
        'submit_ts': 'number',
        'update_ts': 'number'
    },
    'external_details': 'string',
    'progress': 'number',
    'rerun': {
        'retried_by': 'string',
        'retry': 'False|True'
    },
    'retried_by': [
        'string'
    ],
    'search_end': 'number',
    'search_start': 'number',
    'search_status': 'pending'|'failed'|'suspended'|'complete'|'released',
    'search_uuid': 'string',
    'status_details': 'string',
    'total_found': 'number'
}

Response Definitions

account_id (string) –

The AIMS Account ID

authoritative_retry (string) –

The UUID of the first successful search that was a retry of this search. This field is only populated when search_status is or was failed. If this field is populated, its value will always be in retried_by.

details (dict) – [REQUIRED]

cost (dict) – [REQUIRED]

A map containing the costs of various components of the search, if you have permission to view such data.

total (number) –

The total cost of the search.

request (string) –

The SQL query that was submitted for the search.

requested_type (dict) –

The type of the search that was requested. This may also be “unknown” for v1 searches which have been wrapped to be v2 searches.

search_type (dict) –

The type of the search. This may also be “unknown” for v1 searches which have been wrapped to be v2 searches.

stats (dict) –

Internal statistics of the search.

submit_ts (number) –

An epoch timestamp of when the search was submitted. This is also the value of NOW() in the search.

update_ts (number) –

An epoch timestamp of when the search was last updated.

external_details (string) –

An external-facing description that gives more details to the search_status field.

progress (number) –

An estimate of the progress of the search completion on a scale of 0-100.

rerun (dict) – [REQUIRED]

An object describing the search this search is a rerun of.

retried_by (uuid) –

A unique identifier for a search

retry (boolean) –

If true, this search is a retry of the search in retried_by because that search failed.

retried_by (list) –

A list of search UUIDs of searches that are retries of this search, in the order the retries were launched. This field is only populated after a search fails (i.e. the search_status is or was failed).

(uuid) –

A unique identifier for a search

search_end (number) –

Unix timestamp of requested search timeframe end

search_start (number) –

Unix timestamp of requested search timeframe beginning

search_status (string) –

The state of the search.

pending is running

suspended is a search that has partially run but is no longer executing

failed is a search that encountered an error

complete is a search that completed successfully

released is a search that has been stopped and/or had its results deleted.

Valid values: pending, failed, suspended, complete, released

search_uuid (uuid) –

A unique identifier for a search

status_details (string) –

An internal-facing description of the search_status field, typically used for failed searches.

total_found (number) –

The number of results found in the search.

validate_search(**kwargs)¶

Validates the SQL query for Expert Mode Search usage

Request Syntax

response = client.validate_search(
    data='string'
    end='integer'
    start='integer'
    timeframe='integer'
    x_invoked_by='string'
)

Parameters

data (string) –
end (integer) – Option to specify the end of search query time frame. This must be used with end parameter. If start, end or timeframe are used in conjunction with a search query that has exact timeframe conditions, the URL query parameters are ignored. This parameter is mutually exclusive with timeframe.
start (integer) – Option to specify the start of search query time frame. This must be used with end parameter. If start, end or timeframe are used in conjunction with a search query that has exact timeframe conditions, the URL query parameters are ignored. This parameter is mutually exclusive with timeframe.
timeframe (integer) – Option to specify the search time frame duration in past seconds. If start, end or timeframe are used in conjunction with a search query that has exact timeframe conditions, the URL query parameters are ignored. This parameter is mutually exclusive with start and end.
x_invoked_by (string) –
A one or two-word description of your client

Default: openapi-client

Return type

dict

Returns

Response Syntax

{
    'data_type': 'string'
}

Response Definitions

data_type (string) –

The data type being searched, that a particular message belongs to, or detected in a query.

Search¶

Client¶

Search ¶

Client ¶