Search
A search request that iterates over its search results. |
|
A search request that iterates over its search results for images. |
|
The readonly data returned by |
|
The readonly data returned by |
|
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:
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()
orImage.search()
.You must use the
Search
object as aniterator
to get the results. This will execute the search query and return a generator for iterating through the returned results. This might raise aBadRequestError
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 theand
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 thein_()
orany_of()
method. You cannot use the boolean keywordsand
andor
because of Python language limitations; instead combine filter expressions using&
(boolean “and”) and|
(boolean “or”). Filters usinglike()
are not supported.- Returns:
A new
Search
instance with the new filter(s) applied (usingand
if there were existing filters)- Return type:
- 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 tofind_text
override the previous find_text parameter.
- 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:
- 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:
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 toSearch
but with a couple of summary methods:summary()
andsummary_interval()
.Classes:
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:
- 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:
- 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 theand
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 thein_()
orany_of()
method. You cannot use the boolean keywordsand
andor
because of Python language limitations; instead combine filter expressions using&
(boolean “and”) and|
(boolean “or”). Filters usinglike()
are not supported.- Returns:
A new
Search
instance with the new filter(s) applied (usingand
if there were existing filters)- Return type:
- 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 tofind_text
override the previous find_text parameter.
- 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:
- 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:
- 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:
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 isACQUIRED
. 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 isYEAR
.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 value0
.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 value0
.
- 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()
orSummaySearch.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()
orSummaySearch.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
Attributes:props