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)[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.
Returns:
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.
Returns:
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)[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().

Attributes:

DEFAULT_AGGREGATE_DATE_FIELD

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

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)¶

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.) –
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.
Returns:
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.
Returns:
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 descarteslabs.common.property_filtering.filtering.Properties Attributes:

props