Search

class Search(session_kwargs, client, return_type='raw')

Methods

list(*[, query, type, offset, order, owner, ...])	Perform a search
list_queries(*[, search_string, ...])	Search queries that are not hidden
list_types()	List available search types

Examples

>>> import civis
>>> client = civis.APIClient()
>>> client.search.list(...)

list(*, query: str = None, type: str = None, offset: int = None, order: str = None, owner: str = None, limit: int = None, archived: str = None, last_run_state: str = None) → Response

Perform a search

Parameters:

querystr, optional

The search query.

typestr, optional

The type for the search. It accepts a comma-separated list. Valid arguments are listed on the “GET /search/types” endpoint.

offsetint, optional

The offset for the search results.

orderstr, optional

The field on which to order the result set.

ownerstr, optional

The owner for the search.

limitint, optional

Defaults to 10. Maximum allowed is 1000.

archivedstr, optional

If specified, return only results with the chosen archived status; either ‘true’, ‘false’, or ‘all’. Defaults to ‘false’.

last_run_statestr, optional

The last run state of the job being searched for; either: ‘queued’, ‘running’, ‘succeeded’, ‘failed’, or ‘cancelled’.

Returns:

civis.Response

• total_resultsint

  The number of items matching the search query.

• aggregationscivis.Response

  Aggregations by owner and type for the search results.

• resultsList[civis.Response]

  The items returned by the search.

  • scorefloat (float)

    The relevance score from the search request.

  • typestr

    The type of the item.

  • idint

    The ID of the item.

  • namestr

    The name of the item.

  • type_namestr

    The verbose name of the type.

  • updated_atstr (time)

    The time the item was last updated.

  • ownerstr

    The owner of the item.

  • use_countint

    The use count of the item, if the item is a template.

  • last_run_idint

    The last run id of the item, if the item is a job.

  • last_run_statestr

    The last run state of the item, if the item is a job.

  • last_run_startstr (time)

    The last run start time of the item, if the item is a job.

  • last_run_finishstr (time)

    The last run finish time of the item, if the item is a job.

  • publicbool

    The flag that indicates a template is available to all users.

  • last_run_exceptionstr

    The exception of the item after the last run, if the item is a job.

  • auto_sharebool

    The flag that indicates if a project has Auto-Share enabled.

list_queries(*, search_string: str = None, database_id: int = None, credential_id: int = None, author_id: int = None, archived: bool = None, state: List[str] = None, started_before: str = None, started_after: str = None, limit: int = None, page_num: int = None, order: str = None, order_dir: str = None, iterator: bool = None) → list[Response] | PaginatedResponse

Search queries that are not hidden

Parameters:

search_stringstr, optional

Space delimited search terms for searching queries by their SQL. Supports wild card characters “?” for any single character, and “*” for zero or more characters.

database_idint, optional

The database ID.

credential_idint, optional

The credential ID.

author_idint, optional

The author of the query.

archivedbool, optional

The archival status of the requested item(s). Defaults to false.

stateList[str], optional

The state of the last run. One or more of queued, running, succeeded, failed, and cancelled.

started_beforestr, optional

An upper bound for the start date of the last run.

started_afterstr, optional

A lower bound for the start date of the last run.

limitint, optional

Number of results to return. Defaults to 10. Maximum allowed is 50.

page_numint, optional

Page number of the results to return. Defaults to the first page, 1.

orderstr, optional

The field on which to order the result set. Defaults to last_run_started_at. Must be one of: last_run_started_at.

order_dirstr, optional

Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.

iteratorbool, optional

If True, return a generator (specifically, a civis.PaginatedResponse object) to iterate over all responses. Use it when more results than the maximum allowed by ‘limit’ are needed. When True, ‘page_num’ is ignored. If False, return a list of civis.Response objects, whose size is determined by ‘limit’. Defaults to False.

Returns:

civis.PaginatedResponse

• idint

  The query ID.

• databaseint

  The database ID.

• credentialint

  The credential ID.

• sqlstr

  The SQL executed by the query.

• author_idint

  The author of the query.

• archivedbool

  The archival status of the requested item(s).

• created_at : str (time)

• updated_at : str (time)

• last_runcivis.Response

  • id : int

  • statestr

    The state of the run. One of queued, running, succeeded, failed, and cancelled.

  • started_atstr (time)

    The time that the run started.

  • finished_atstr (time)

    The time that the run completed.

  • errorstr

    The error message for this run, if present.

list_types() → Response

List available search types

Returns:

civis.Response

• typestr

  The name of the item type.