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:
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: 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: 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 tofind_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: 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 toSearch
but with a couple of summary methods:summary()
andsummary_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: 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: 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 tofind_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: 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])
- aggregate_date_field (str or AggregateDateField, optional) – The date field to use for aggregating summary results over time. Valid
inputs are
-
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
descarteslabs.common.property_filtering.filtering.Properties
Attributes:props