Search¶
Client¶
-
class
Search.
Client
¶ A client object representing ‘Search’ Service:
import almdrlib client = almdrlib.client('search')
Available methods:
-
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 wasfailed
. If this field is populated, its value will always be inretried_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 wasfailed
).(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 theget_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
andoffset
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 resultsx_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 wasfailed
. If this field is populated, its value will always be inretried_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 inretried_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 wasfailed
).(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 runningsuspended
is a search that has partially run but is no longer executingfailed
is a search that encountered an errorcomplete
is a search that completed successfullyreleased
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 thetimeframe
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 tofalse
.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. Ifstart
,end
ortimeframe
are used in conjunction with a search query that has exact timeframe conditions, the URL query parameters are ignored. This parameter is mutually exclusive withtimeframe
.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 theinteractive
orbatch
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. Ifstart
,end
ortimeframe
are used in conjunction with a search query that has exact timeframe conditions, the URL query parameters are ignored. This parameter is mutually exclusive withtimeframe
.timeframe (integer) – Option to specify the search time frame duration in past seconds. If
start
,end
ortimeframe
are used in conjunction with a search query that has exact timeframe conditions, the URL query parameters are ignored. This parameter is mutually exclusive withstart
andend
.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 wasfailed
. If this field is populated, its value will always be inretried_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 inretried_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 wasfailed
).(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 runningsuspended
is a search that has partially run but is no longer executingfailed
is a search that encountered an errorcomplete
is a search that completed successfullyreleased
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. Ifstart
,end
ortimeframe
are used in conjunction with a search query that has exact timeframe conditions, the URL query parameters are ignored. This parameter is mutually exclusive withtimeframe
.start (integer) – Option to specify the start of search query time frame. This must be used with
end
parameter. Ifstart
,end
ortimeframe
are used in conjunction with a search query that has exact timeframe conditions, the URL query parameters are ignored. This parameter is mutually exclusive withtimeframe
.timeframe (integer) – Option to specify the search time frame duration in past seconds. If
start
,end
ortimeframe
are used in conjunction with a search query that has exact timeframe conditions, the URL query parameters are ignored. This parameter is mutually exclusive withstart
andend
.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.