Search

`Search`	A search request that iterates over its search results.
`ImageSearch`	A search request that iterates over its search results for images.
`BlobSummaryResult`	The readonly data returned by `SummaySearch.summary()` or `SummaySearch.summary_interval()`.
`ImageSummaryResult`	The readonly data returned by `SummaySearch.summary()` or `SummaySearch.summary_interval()`.
`properties`	A wrapper object to construct filter properties by referencing instance attributes.

class Search(model, client=None, url=None, includes=True, request_params=None, headers=None)[source]

A search request that iterates over its search results.

You can narrow your search by using the following methods on the search object:

limit()
filter()
find_text()

Each method on a search instance returns a narrowed-down search object. You obtain a search instance using the search() method on a catalog object class, for example Product.search(), Band.search() or Image.search().

You must use the Search object as an iterator to get the results. This will execute the search query and return a generator for iterating through the returned results. This might raise a BadRequestError if any of the query parameters or filters are invalid.

Example

>>> from descarteslabs.catalog import Product, Search, properties as p
>>> search = Search(Product).filter(p.start_datetime >= "2012-01-01")
>>> list(search) 

Methods:

`collect`(**kwargs)	Execute the search query and return the appropriate collection.
`count`()	Fetch the number of documents that match the search.
`filter`(properties)	Filter results by the values of various fields.
`find_text`(text)	Full-text search for a string in the name or description of an item.
`limit`(limit)	Limit the number of search results returned by the search execution.
`sort`(field[, ascending])	Sort the returned results by the given field.

collect(**kwargs)[source]

Execute the search query and return the appropriate collection.

Returns:

Collection of objects that match the type of document beng searched.

Return type:

Collection

Raises:

BadRequestError – If any of the query parameters or filters are invalid
ClientError or ServerError – Spurious exception that can occur during a network request.

count()[source]

Fetch the number of documents that match the search.

Note that this may not be an exact count if searching within a geometry.

Returns:

Number of matching records

Return type:

int

Raises:

BadRequestError – If any of the query parameters or filters are invalid
ClientError or ServerError – Spurious exception that can occur during a network request.

Example

>>> from descarteslabs.catalog import Band, Search, properties as p
>>> search = Search(Band).filter(p.type=="spectral")
>>> count = search.count() 

filter(properties)[source]

Filter results by the values of various fields.

Successive calls to filter will add the new filter(s) using the and Boolean operator (&).

Parameters:: properties (Expression) – Expression used to filter objects in the search by their properties, built from properties. You can construct filter expressions using the ==, !=, <, >, <= and >= operators as well as the in_() or any_of() method. You cannot use the boolean keywords and and or because of Python language limitations; instead combine filter expressions using & (boolean “and”) and | (boolean “or”). Filters using like() are not supported.
Returns:: A new Search instance with the new filter(s) applied (using and if there were existing filters)
Return type:: Search
Raises:: ValueError – If the properties filter provided is not supported.

Example

>>> from descarteslabs.catalog import Product, Search, properties as p
>>> search = Search(Product).filter(
...     (p.resolution_min < 60) & (p.start_datetime > "2000-01-01")
... )
>>> list(search) 

find_text(text)[source]

Full-text search for a string in the name or description of an item.

Not all attributes support full-text search; the product name (Product.name) and product and band description (Product.description, Band.description) support full-text search. Successive calls to find_text override the previous find_text parameter.

Parameters:: text (str) – A string you want to perform a full-text search for.
Returns:: A new instance of the Search class that includes the text query.
Return type:: Search

limit(limit)[source]

Limit the number of search results returned by the search execution.

Successive calls to limit will overwrite the previous limit parameter.

Parameters:: limit (int) – The maximum number of records to return.
Return type:: Search

sort(field, ascending=True)[source]

Sort the returned results by the given field.

Multiple sort fields are not supported, so successive calls to sort will overwrite the previous sort parameter.

Parameters:

field (str) – The name of the field to sort by
ascending (bool) – Sorts results in ascending order if True and descending order if False.

Return type:

Search

Example

>>> from descarteslabs.catalog import Product, Search
>>> search = Search(Product).sort("created", ascending=False)
>>> list(search) 

class ImageSearch(model, client=None, url=None, includes=True, request_params=None, headers=None)[source]

A search request that iterates over its search results for images.

The ImageSearch is identical to Search but with a couple of summary methods: summary() and summary_interval().

Classes:

SummaryResult

alias of ImageSummaryResult

Methods:

`collect`([geocontext])	Execute the search query and return the collection of the appropriate type.
`count`()	Fetch the number of documents that match the search.
`filter`(properties)	Filter results by the values of various fields.
`find_text`(text)	Full-text search for a string in the name or description of an item.
`intersects`(geometry[, match_null_geometry])	Filter images or blobs to those that intersect the given geometry.
`limit`(limit)	Limit the number of search results returned by the search execution.
`sort`(field[, ascending])	Sort the returned results by the given field.
`summary`()	Get summary statistics about the current `Search` query.
`summary_interval`([aggregate_date_field, ...])	Get summary statistics by specified datetime intervals about the current `ImageSearch` query.

Attributes:

DEFAULT_AGGREGATE_DATE_FIELD

SummaryResult: alias of ImageSummaryResult

collect(geocontext=None, **kwargs)[source]

Execute the search query and return the collection of the appropriate type.

Parameters:

geocontext (shapely.geometry.base.BaseGeometry, descarteslabs.common.geo.Geocontext, geojson-like, default None # noqa: E501) – AOI for the ImageCollection.

Returns:

ImageCollection of Images returned from the search.

Return type:

ImageCollection

Raises:

BadRequestError – If any of the query parameters or filters are invalid
ClientError or ServerError – Spurious exception that can occur during a network request.

count()

Fetch the number of documents that match the search.

Note that this may not be an exact count if searching within a geometry.

Returns:

Number of matching records

Return type:

int

Raises:

BadRequestError – If any of the query parameters or filters are invalid
ClientError or ServerError – Spurious exception that can occur during a network request.

Example

>>> from descarteslabs.catalog import Band, Search, properties as p
>>> search = Search(Band).filter(p.type=="spectral")
>>> count = search.count() 

filter(properties)

Filter results by the values of various fields.

Successive calls to filter will add the new filter(s) using the and Boolean operator (&).

Parameters:: properties (Expression) – Expression used to filter objects in the search by their properties, built from properties. You can construct filter expressions using the ==, !=, <, >, <= and >= operators as well as the in_() or any_of() method. You cannot use the boolean keywords and and or because of Python language limitations; instead combine filter expressions using & (boolean “and”) and | (boolean “or”). Filters using like() are not supported.
Returns:: A new Search instance with the new filter(s) applied (using and if there were existing filters)
Return type:: Search
Raises:: ValueError – If the properties filter provided is not supported.

Example

>>> from descarteslabs.catalog import Product, Search, properties as p
>>> search = Search(Product).filter(
...     (p.resolution_min < 60) & (p.start_datetime > "2000-01-01")
... )
>>> list(search) 

find_text(text)

Full-text search for a string in the name or description of an item.

Not all attributes support full-text search; the product name (Product.name) and product and band description (Product.description, Band.description) support full-text search. Successive calls to find_text override the previous find_text parameter.

Parameters:: text (str) – A string you want to perform a full-text search for.
Returns:: A new instance of the Search class that includes the text query.
Return type:: Search

intersects(geometry, match_null_geometry=False)

Filter images or blobs to those that intersect the given geometry.

Successive calls to intersects override the previous intersection geometry.

Parameters:

geometry (shapely.geometry.base.BaseGeometry, GeoContext, geojson-like Geometry that found images must intersect.) –
match_null_geometry (bool, optional (default False) Also match images or blobs with no geometry.) –

Returns:

A new instance of the GeoSearch class that includes geometry filter.

Return type:

Search

limit(limit)

Limit the number of search results returned by the search execution.

Successive calls to limit will overwrite the previous limit parameter.

Parameters:: limit (int) – The maximum number of records to return.
Return type:: Search

sort(field, ascending=True)

Sort the returned results by the given field.

Multiple sort fields are not supported, so successive calls to sort will overwrite the previous sort parameter.

Parameters:

field (str) – The name of the field to sort by
ascending (bool) – Sorts results in ascending order if True and descending order if False.

Return type:

Search

Example

>>> from descarteslabs.catalog import Product, Search
>>> search = Search(Product).sort("created", ascending=False)
>>> list(search) 

summary()

Get summary statistics about the current Search query.

Returns:: The summary statistics as a SummaryResult object.
Return type:: SummaryResult
Raises:: ClientError or ServerError – Spurious exception that can occur during a network request.

Example

>>> from descarteslabs.catalog import Image, properties as p
>>> search = Image.search().filter(
...     p.product_id=="landsat:LC08:01:RT:TOAR"
... )
>>> s = search.summary() 
>>> print(s.count, s.bytes) 

summary_interval(aggregate_date_field=None, interval='year', start_datetime=None, end_datetime=None)

Get summary statistics by specified datetime intervals about the current ImageSearch query.

Parameters:

aggregate_date_field (str or AggregateDateField, optional) – The date field to use for aggregating summary results over time. Valid inputs are ACQUIRED, CREATED, MODIFIED, PUBLISHED. The default is ACQUIRED. Field must be defined for the class.
interval (str or Interval, optional) – The time interval to use for aggregating summary results. Valid inputs are YEAR, QUARTER, MONTH, WEEK, DAY, HOUR, MINUTE. The default is YEAR.
start_datetime (str or datetime, optional) – Beginning of the date range over which to summarize data in ISO format. The default is least recent date found in the search result based on the aggregate_date_field. The start_datetime is included in the result. To set it as unbounded, use the value 0.
end_datetime (str or datetime, optional) – End of the date range over which to summarize data in ISO format. The default is most recent date found in the search result based on the aggregate_date_field. The end_datetime is included in the result. To set it as unbounded, use the value 0.

Returns:

The summary statistics for each interval, as a list of SummaryResult objects.

Return type:

list(SummaryResult)

Raises:

ClientError or ServerError – Spurious exception that can occur during a network request.

Example

>>> from descarteslabs.catalog import Image, AggregateDateField, Interval, properties
>>> search = (
...     Image.search()
...     .filter(properties.product_id == "landsat:LC08:01:RT:TOAR")
... )
>>> interval_results = search.summary_interval(
...         aggregate_date_field=AggregateDateField.ACQUIRED, interval=Interval.MONTH
... ) 
>>> print([(i.interval_start, i.count) for i in interval_results]) 

DEFAULT_AGGREGATE_DATE_FIELD = 'acquired'

class BlobSummaryResult(count=None, bytes=None, namespaces=None, interval_start=None, **kwargs)[source]

The readonly data returned by SummaySearch.summary() or SummaySearch.summary_interval().

count

Number of blobs in the summary.

Type:: int

bytes

Total number of bytes of data across all blobs in the summary.

Type:: int

namespaces

List of namespace IDs for the blobs included in the summary.

Type:: list(str)

interval_start

For interval summaries only, a datetime representing the start of the interval period.

Type:: datetime

class ImageSummaryResult(count=None, bytes=None, products=None, interval_start=None, **kwargs)[source]

The readonly data returned by SummaySearch.summary() or SummaySearch.summary_interval().

count

Number of images in the summary.

Type:: int

bytes

Total number of bytes of data across all images in the summary.

Type:: int

products

List of IDs for the products included in the summary.

Type:: list(str)

interval_start

For interval summaries only, a datetime representing the start of the interval period.

Type:: datetime

properties: alias of Properties