Vector¶
Warning
This low-level client has been replaced with the object-oriented Tables client.
-
class
Vector
(url=None, auth=None)[source]¶ Client for storing and querying vector data.
The Descartes Labs Vector service allows you store vector features (points, polygons, etc.) with associated key-value properties, and query that data by geometry or by properties.
It works best at the scale of millions of features. For small amounts of vector data that easily fit in memory, working directly with a GeoJSON file or similar may be more efficient.
Concepts:
- “Feature”: a single geometric entity and its associated metadata (equivalent to a GeoJSON Feature).
- “Product”: a collection of related Features, with a common id, description, and access controls.
This client currently returns data as dictionaries in JSON API format.
Parameters: - url (str) – URL for the vector service. Only change
this if you are being asked to use a non-default Descartes Labs catalog. If
not set, then
descarteslabs.config.get_settings().VECTOR_URL
will be used. - auth (Auth) – A custom user authentication (defaults to the user authenticated locally by token information on disk or by environment variables)
- retries (urllib3.util.retry.Retry) – A custom retry configuration used for all API requests (defaults to a reasonable amount of retries)
Attributes:
SEARCH_PAGE_SIZE
TIMEOUT
properties
Methods:
count_features
(product_id)Get the count of the features in a product. create_feature
(product_id, geometry[, …])Add a feature to an existing vector product. create_features
(product_id, features[, …])Add multiple features to an existing vector product. create_product
(product_id, title, description)Add a vector product to your catalog. create_product_from_query
(new_product_id, …)Query vector features within an existing product and create a new vector product to your catalog from the query result. delete_features_from_query
(product_id[, …])Query an existing Vector product and delete features that match the query results. delete_product
(product_id)Remove a vector product from the catalog. export_product_from_query
(product_id, key[, …])Query vector features within an existing product and export the result to DescartesLabs Storage as type data
using the given storage key.get_delete_features_status
(product_id)Get the status of the job deleting features from a query. get_export_result
(product_id, export_id)Get details about a specific export job. get_export_results
(product_id)Get a list of the exports submitted to a vector product, and status information about each. get_product
(product_id)Get a product’s properties. get_product_from_query_status
(product_id)Get the status of the job creating a new product from a query. get_upload_result
(product_id, upload_id[, …])Get details about a specific upload job. get_upload_results
(product_id[, pending])Get a list of the uploads submitted to a vector product, and status information about each. list_products
([page_size, page])Get all vector products that you have access using JSON API pagination. replace_product
([product_id, name, title, …])Replace a vector product in your catalog. search_features
(product_id[, geometry, …])Iterate over vector features within an existing product. update_product
(product_id[, name, title, …])Update a vector product in your catalog using the given parameters. upload_features
(file_ish, product_id[, …])Asynchonously upload a file or stream of Newline Delimited JSON features.Note that the file may not contain empty lines or lines containing anything but the feature (including e.g.a trailing comma), or such lines will cause errors.. -
count_features
(product_id)[source]¶ Get the count of the features in a product.
Parameters: product_id (str) – (Required) The ID of the product to count all features for.
Return type: int
Returns: The total number of features in a product.
Raises: - NotFoundError – Raised if the product cannot be found.
- RateLimitError – Raised when too many requests have been made within a given time period.
- ServerError – Raised when a unknown error occurred on the server.
-
create_feature
(product_id, geometry, properties=None, fix_geometry='accept')[source]¶ Add a feature to an existing vector product.
Parameters: - product_id (str) – (Required) The ID of the Vector product to which this feature will belong.
- geometry (dict) –
(Required) Shape associated with this vector feature. This accepts the following types of GeoJSON or Shapely geometries:
- Points
- MultiPoints
- Polygons
- MultiPolygons
- LineStrings
- MultiLineStrings
- GeometryCollections
- properties (dict) – Dictionary of arbitrary properties.
- fix_geometry (str) – String specifying how to handle certain problem
geometries, including those which do not follow counter-clockwise
winding order (which is required by the GeoJSON spec but not many
popular tools). Allowed values are
reject
(reject invalid geometries with an error),fix
(correct invalid geometries if possible and use this corrected value when creating the feature), andaccept
(the default) which will correct the geometry for internal use but retain the original geometry in the results.
Return type: Returns: Created Feature, as a JSON API resource collection. The keys are:
data: A "DotDict" instance with the following keys: id: The ID of the feature. type: "feature". attributes: A DotDict instance with the following keys: created: Time that the task was created in ISO-8601 UTC. properties: A DotDict instance. The keys are user provided. Supported values are strings, numbers, the value "None". geometry: A DotDict instance with the following keys: type: The type of the feature, one of ["Polygon", "MultiPolygon", "Point", "MultiPoint", "LineString", "MultiLineString", or "GeometryCollection"]. coordinates: A list of coordinates; the exact structure of potentially nesting lists depends on the given type.
Raises: - NotFoundError – Raised if the product cannot be found.
- BadRequestError – Raised when the request is malformed, e.g. the owners list is missing prefixes.
- RateLimitError – Raised when too many requests have been made within a given time period.
- ServerError – Raised when a unknown error occurred on the server.
-
create_features
(product_id, features, fix_geometry='accept')[source]¶ Add multiple features to an existing vector product.
Parameters: - product_id (str) – (Required) The ID of the Vector product to which these features will belong.
- features (list(dict)) – (Required) Each feature must be a dict with a geometry
and properties field. If you provide more than 100 features,
they will be batched in
groups of 100, but consider using
upload_features()
instead. - fix_geometry (str) – String specifying how to handle certain problem
geometries, including those which do not follow counter-clockwise
winding order (which is required by the GeoJSON spec but not many
popular tools). Allowed values are
reject
(reject invalid geometries with an error),fix
(correct invalid geometries if possible and use this corrected value when creating the feature), andaccept
(the default) which will correct the geometry for internal use but retain the original geometry in the results.
Return type: Returns: The features as a JSON API resource object. The keys are:
data: A list of "DotDict" instances with the following keys: id: The ID of the feature. type: "feature". attributes: A DotDict instance with the following keys: created: Time that the task was created in ISO-8601 UTC. properties: A DotDict instance. The keys are user provided. Supported values are strings, numbers, the value "None". geometry: A DotDict instance with the following keys: type: The type of the feature, one of ["Polygon", "MultiPolygon", "Point", "MultiPoint", "LineString", "MultiLineString", or "GeometryCollection"]. coordinates: A list of coordinates; the exact structure of potentially nesting lists depends on the given type.
Raises: - NotFoundError – Raised if the product cannot be found.
- BadRequestError – Raised when the request is malformed. May also indicate that too many features were included. If more than 100 features were provided, some of these features may have been successfuly inserted while others may not have been inserted.
- RateLimitError – Raised when too many requests have been made within a given time period.
- ServerError – Raised when a unknown error occurred on the server.
-
create_product
(product_id, title, description, owners=None, readers=None, writers=None)[source]¶ Add a vector product to your catalog.
Parameters: - product_id (str) – (Required) A unique name for this Vector product.
In the created product a namespace consisting of your user id (e.g.
ae60fc891312ggadc94ade8062213b0063335a3c:
) or your organization id (e.g.,yourcompany:
) will be prefixed to this, if it doesn’t already have one, in order to make the id globally unique. - title (str) – (Required) Official product title.
- description (str) – (Required) Information about the product, why it exists, and what it provides.
- owners (list(str)) – User, group, or organization IDs that own this product.
Each ID must be prefixed with
user:
,group:
, ororg:
. Defaults to [current user, current user’s org]. - readers (list(str)) – User, group, or organization IDs that can read
this product.
Each ID must be prefixed with
user:
,group:
, ororg:
. - writers (list(str)) – User, group, or organization IDs that can edit
this product.
Each ID must be prefixed with
user:
,group:
, ororg:
.
Return type: Returns: Created vector product, as a JSON API resource object. For a list of keys, please see
get_product()
.Raises: - BadRequestError – Raised when the request is malformed, e.g. the supplied product id is already in use.
- RateLimitError – Raised when too many requests have been made within a given time period.
- ServerError – Raised when a unknown error occurred on the server.
- product_id (str) – (Required) A unique name for this Vector product.
In the created product a namespace consisting of your user id (e.g.
-
create_product_from_query
(new_product_id, title, description, product_id, owners=None, readers=None, writers=None, geometry=None, query_expr=None, query_limit=None)[source]¶ Query vector features within an existing product and create a new vector product to your catalog from the query result.
At least one of
geometry
,query_expr
, orquery_limit
is required.Parameters: - new_product_id (str) – (Required) A unique name for this product.
In the created product a namespace consisting of your user id (e.g.
ae60fc891312ggadc94ade8062213b0063335a3c:
) or your organization id (e.g.,yourcompany:
) will be prefixed to this, if it doesn’t already have one, in order to make the id globally unique. - title (str) – (Required) Official product title.
- description (str) – (Required) Information about the product, why it exists, and what it provides.
- product_id (str) – (Required) The ID of the product within which to search.
- owners (list(str)) – User, group, or organization IDs that own this product.
Each ID must be prefixed with
user:
,group:
, ororg:
. Defaults to [current user, current user’s org]. - readers (list(str)) – User, group, or organization IDs that can read this
product. Each ID must be prefixed with
user:
,group:
, ororg:
. - writers (list(str)) – User, group, or organization IDs that can edit this
product. Each ID must be prefixed with
user:
,group:
, ororg:
. - geometry (dict) –
Search for Features intersecting this shape. This accepts the following types of GeoJSON or Shapely geometries:
- Points
- MultiPoints
- Polygons
- MultiPolygons
- LineStrings
- MultiLineStrings
- GeometryCollections
- query_expr (Expression) – Expression used to filter features by their properties, built from
dl.properties
. You can construct filter expression using the==
,!=
,<
,>
,<=
and>=
operators as well as thelike()
andin_()
methods. You cannot use the boolean keywordsand
andor
because of Python language limitations; instead you can combine filter expressions with&
(boolean “and”) and|
(boolean “or”). Example (assumingfrom descarteslabs import properties as p
):query_expr=(p.temperature >= 50) & (p.hour_of_day > 18)
. More complex example:query_expr=(100 > p.temperature >= 50) | ((p.month != 10) & (p.day_of_month > 14))
. If you supply a property which doesn’t exist as part of the expression that comparison will evaluate toFalse
. - query_limit (int) – Maximum number of features to return for this query, defaults to all.
Return type: Returns: Created vector product, as a JSON API resource object. For a description of the keys, please see
get_product()
.Raises: - BadRequestError – Raised when the request is malformed, e.g. the supplied new product id is already in use.
- NotFoundError – Raised if the product cannot be found.
- RateLimitError – Raised when too many requests have been made within a given time period.
- ServerError – Raised when a unknown error occurred on the server.
- new_product_id (str) – (Required) A unique name for this product.
In the created product a namespace consisting of your user id (e.g.
-
delete_features_from_query
(product_id, geometry=None, query_expr=None, **kwargs)[source]¶ Query an existing Vector product and delete features that match the query results.
One of
geometry
orquery_expr
is required.Parameters: - product_id (str) – (Required) The ID of the product within which to search for features to delete.
- geometry (dict) –
Search for Features intersecting this shape. This accepts the following types of GeoJSON or Shapely geometries:
- Points
- MultiPoints
- Polygons
- MultiPolygons
- LineStrings
- MultiLineStrings
- GeometryCollections
- query_expr (Expression) – Expression used to filter features by their properties, built from
dl.properties
. You can construct filter expression using the==
,!=
,<
,>
,<=
and>=
operators as well as thelike()
andin_()
methods. You cannot use the boolean keywordsand
andor
because of Python language limitations; instead you can combine filter expressions with&
(boolean “and”) and|
(boolean “or”). Example (assumingfrom descarteslabs import properties as p
):query_expr=(p.temperature >= 50) & (p.hour_of_day > 18)
. More complex example:query_expr=(100 > p.temperature >= 50) | ((p.month != 10) & (p.day_of_month > 14))
. If you supply a property which doesn’t exist as part of the expression that comparison will evaluate toFalse
.
Return type: Returns: Vector product from which the features were deleted, as a JSON API resource object. For a list of keys, please see
get_product()
.Raises: - BadRequestError – Raised when the request is malformed, e.g. the query limit is not a number.
- NotFoundError – Raised if the product cannot be found.
- RateLimitError – Raised when too many requests have been made within a given time period.
- ServerError – Raised when a unknown error occurred on the server.
-
delete_product
(product_id)[source]¶ Remove a vector product from the catalog.
Parameters: product_id (str) – (Required) The ID of the Vector product to remove.
Raises: - NotFoundError – Raised if the product cannot be found.
- RateLimitError – Raised when too many requests have been made within a given time period.
- ServerError – Raised when a unknown error occurred on the server.
-
export_product_from_query
(product_id, key, geometry=None, query_expr=None, query_limit=None)[source]¶ Query vector features within an existing product and export the result to DescartesLabs Storage as type
data
using the given storage key.If none of the
geometry
,query_expr
, orquery_limit
are given, the full product is exported.Note that the export is happening asynchronously and can take a while depending on the size of the product or query. You can request the status using
get_export_result()
orget_export_results()
.Once the export is complete, you can download the file from Descartes Labs Storage using
descarteslabs.client.services.storage.Storage.get_file()
with the given key and a local filename.Parameters: - product_id (str) – (Required) The ID of the product within which to search or which to copy.
- key (str) – (Required) The name under which the export will be
available in the Storage service. The
storage_type
will bedata
. Note that this will overwrite any existing data if the key already exists. - geometry (dict) –
Search for Features intersecting this shape. This accepts the following types of GeoJSON or Shapely geometries:
- Points
- MultiPoints
- Polygons
- MultiPolygons
- LineStrings
- MultiLineStrings
- GeometryCollections
- query_expr (Expression) – Expression used to filter features by their properties, built from
dl.properties
. You can construct filter expression using the==
,!=
,<
,>
,<=
and>=
operators as well as thelike()
and andin_()
methods. You cannot use the boolean keywordsand
andor
because of Python language limitations; instead you can combine filter expressions with&
(boolean “and”) and|
(boolean “or”). Example (assumingfrom descarteslabs import properties as p
):query_expr=(p.temperature >= 50) & (p.hour_of_day > 18)
. More complex example:query_expr=(100 > p.temperature >= 50) | ((p.month != 10) & (p.day_of_month > 14))
. If you supply a property which doesn’t exist as part of the expression that comparison will evaluate toFalse
. - query_limit (int) – Maximum number of features to return for this query, defaults to all.
Return type: str
Returns: The export id.
Raises: - BadRequestError – Raised when the request is malformed, e.g. the query limit is not a number.
- NotFoundError – Raised if the product cannot be found.
- RateLimitError – Raised when too many requests have been made within a given time period.
- ServerError – Raised when a unknown error occurred on the server.
-
get_delete_features_status
(product_id)[source]¶ Get the status of the job deleting features from a query.
Parameters: product_id (str) – (Required) The ID of the product to get delete status for. the previously initiated deletion using
create_product()
orcreate_product_from_query()
.Rtype DotDict: Returns: A dictionary with information about the status. For a description of the keys, please see
get_product_from_query_status()
. Note that thetype
will bedelete_job
.Raises: - NotFoundError – Raised if the product cannot be found.
- RateLimitError – Raised when too many requests have been made within a given time period.
- ServerError – Raised when a unknown error occurred on the server.
-
get_export_result
(product_id, export_id)[source]¶ Get details about a specific export job. Included information about processing error streams, which can help debug failed uploads. Note that this information is available once the job completed (either successfully or unsuccessfully).
Parameters: - product_id (str) – (Required) The ID of the product for which to return the result.
- export_id (str) – (Required) The export ID for which to return
the result, as previously returned by
export_product_from_query()
.
Return type: Returns: The information about the export task once the task has completed. The keys are:
data: A single "DotDict" instance with the following keys: id: The id of the task. type: export. attributes: A DotDict instance with the following keys: created: Time that the task was created in ISO-8601 UTC. exception_name: The type of exception, if there is one, "None" otherwise. failure_type: "executable_failure" if resource limits are reached, or "exception" if an exception was thrown, "None" otherwise. peak_memory_usage: The amount of memory used by the task in bytes. runtime: The number of CPU seconds used by the task. status: "SUCCESS" or "FAILURE". labels: A list of string labels. The last value is the key.
Raises: - NotFoundError – When the task is either not found or the task is pending or running but has not completed yet.
- RateLimitError – Raised when too many requests have been made within a given time period.
- ServerError – Raised when a unknown error occurred on the server.
-
get_export_results
(product_id)[source]¶ Get a list of the exports submitted to a vector product, and status information about each. Note that only completed tasks are shown; any tasks that are pending or running will not be listed.
Parameters: product_id (str) – (Required) The ID of the product to get results for.
Return type: Iterator of
DotDict
instancesReturns: An iterator returning
DotDict
instances containing information about each completed export task created byexport_product_from_query()
. Seeget_export_result()
underdata
for an explanation of the information returned.Raises: - NotFoundError – Raised if the product cannot be found.
- RateLimitError – Raised when too many requests have been made within a given time period.
- ServerError – Raised when a unknown error occurred on the server.
-
get_product
(product_id)[source]¶ Get a product’s properties.
Parameters: product_id (str) – (Required) The ID of the Vector product to fetch.
Return type: Returns: The vector product, as a JSON API resource object. The keys are:
data: A single "DotDict" instance with the following keys: id: The ID of the Vector product. type: "product". meta: A single DotDict instance with the following keys: created: Time that the task was created in ISO-8601 UTC. attributes: A single DotDict instance with the following keys: description: The description given to this product. owners: The owners of this product (at a minimum the organization and the user who created this product). readers: The users, groups, or organizations that can read this product. title: The title given to this product. writers: The users, groups, or organizations that can write into this product.
Raises: - NotFoundError – Raised if the product cannot be found.
- RateLimitError – Raised when too many requests have been made within a given time period.
- ServerError – Raised when a unknown error occurred on the server.
-
get_product_from_query_status
(product_id)[source]¶ Get the status of the job creating a new product from a query.
Parameters: product_id (str) – (Required) The ID of the product for which to to check the status. This ID must have been created by a call to
create_product_from_query()
.Return type: Returns: A dictionary with information about the status. The keys are
data: A "DotDict" instance with the following keys: id: The internal ID for this job. type: "copy_job". attributes: A DotDict instance with the following keys: created: Time that the task was created in ISO-8601 UTC. ended: Time that the task completed in ISO-8601 UTC (when available). started: Time that the start stared in ISO-8601 UTC (when available). state: "PENDING", "RUNNING", or "DONE".
Raises: - NotFoundError – Raised if the product or status cannot be found.
- RateLimitError – Raised when too many requests have been made within a given time period.
- ServerError – Raised when a unknown error occurred on the server.
-
get_upload_result
(product_id, upload_id, pending=False)[source]¶ Get details about a specific upload job. Included is information about processing error streams, which can help debug failed uploads.
Note that the upload happens in 2 stages: the initial Upload Task which preprocesses the data, and the final Upload Job which does the actual upload. The information about the final Upload Job can be found in the
load
key of the upload result.Parameters: - product_id (str) – (Required) The ID of the product which to retrieve the upload result.
- upload_id (str) – (Required) An id pertaining to this requested upload,
either returned by
get_upload_results()
orupload_features()
. - pending (bool) – If True, include pending upload jobs in the result. Defaults to False.
Rtype DotDict: Returns: The result as a JSON API resource object. The keys are:
data: A DotDict instance with the following keys. Not all keys will available depending on the status of the upload job. Specifically, the "load" key will be available once the "status" is "SUCCESS" and the "result" key will be available once the "status" is "SUCCESS" or "FAILURE". Also be aware that the upload job is not complete until the "load.state" is "DONE". id: The ID of the upload task (which is not the upload ID, but you can use it instead of the upload ID). type: "upload". attributes: A DotDict instance with the following keys: created: Time that the task was created in ISO-8601 UTC. exception_name: The type of exception, if there is one, "None" otherwise. failure_type: "executable_failure" if resource limits are reached, or "exception" if an exception was thrown, "None" otherwise. peak_memory_usage: The amount of memory used by the task in bytes. runtime: The number of CPU seconds used by the task. status: The status of the initial Upload Task. "PENDING", "RUNNING", "SUCCESS" or "FAILURE". labels: A list of string labels. The last value is the upload ID. load: A DotDict instance describing the actual result of the final Upload Job which continues asynchronously after the initial Upload Task has completed. The upload is complete once "load.state" is "DONE" or "SKIPPED". This key is only available once "status" is "SUCCESS": errors: How many errors the load caused. output_rows: The number of actual rows created during the load (which may differ from the number of rows given in the upload file). state: The status of the final Upload Job. "SKIPPED", "PENDING", "RUNNING", or "DONE". result: A DotDict instance describing the result of the initial Upload Task (which pre-processes the data before it's loaded). This key is only available once "status" is "SUCCESS" or "FAILURE". errors: A list of errors, potentially empty. input_features: The number of valid rows in the upload file. input_rows: The number of rows that will be loaded (unless there are errors, this should be identical to "output_rows" above). job_id: The internal job ID.
Raises: - NotFoundError – Raised if the product or upload cannot be found.
- RateLimitError – Raised when too many requests have been made within a given time period.
- ServerError – Raised when a unknown error occurred on the server.
-
get_upload_results
(product_id, pending=False)[source]¶ Get a list of the uploads submitted to a vector product, and status information about each.
Parameters: - product_id (str) – (Required) The ID of the Vector product for which to retrieve the upload results
- pending (bool) – If True, include pending upload jobs in the result. Defaults to False.
Return type: Iterator of
DotDict
instancesReturns: An iterator over all upload results created with
upload_features()
, returningDotDict
instances with the following keys:id: The ID of the upload task (which is not the upload ID, but you can use it instead of the upload ID). type: "upload". attributes: A "DotDict" instance with the following keys (note that this contains less information then the information returned by get_upload_result): created: Time that the task was created in ISO-8601 UTC. exception_name: The type of exception, if there is one, "None" otherwise. failure_type: "executable_failure" if resource limits are reached, or "exception" if an exception was thrown, "None" otherwise. peak_memory_usage: The amount of memory used by the task in bytes. runtime: The number of CPU seconds used by the task. status: "RUNNING", "SUCCESS" or "FAILURE". labels: A list of string labels. The last value is the upload ID.
Raises: - NotFoundError – Raised if the product cannot be found.
- RateLimitError – Raised when too many requests have been made within a given time period.
- ServerError – Raised when a unknown error occurred on the server.
-
list_products
(page_size=100, page=1)[source]¶ Get all vector products that you have access using JSON API pagination. The first page (1) will always succeed but may be empty. Subsequent pages may throw
NotFoundError
.Parameters: - page_size (int) – Maximum number of vector products to return per page; default is 100.
- page (int) – Which page of results to fetch, if there are more
results than
page_size
.
Return type: Returns: Available vector products and their properties, as a JSON API collection. This dictionary contains the following keys:
data: A list of DotDict instances with the following keys: id: The ID of the Vector product. type: "product". meta: A single DotDict instance with the following keys: created: Time that the task was created in ISO-8601 UTC. attributes: A single DotDict instance with the following keys: description: The description given to this product. owners: The owners of this product (at a minimum the organization and the user who created this product). readers: The users, groups, or organizations that can read this product. title: The title given to this product. writers: The users, groups, or organizations that can write into this product. links: (Optional) A single DotDict instance with the following keys if there is more than one page of products: next: (Optional) A link to the next page of products if available. prev: (Optional) A link to the previous page of products if available.
Raises: - NotFoundError – Raised if subsequent pages cannot be found.
- RateLimitError – Raised when too many requests have been made within a given time period.
- ServerError – Raised when a unknown error occurred on the server.
-
replace_product
(product_id=None, name=None, title=None, description=None, owners=None, readers=None, writers=None)[source]¶ Replace a vector product in your catalog.
Parameters: - product_id (str) – (Required) The ID of the Vector product to update.
- title (str) – (Required) Official product title.
- description (str) – (Required) Information about the product, why it exists, and what it provides.
- owners (list(str)) – User, group, or organization IDs that own this product.
Each ID must be prefixed with
user:
,group:
, ororg:
. Defaults to [current user, current user’s org]. - readers (list(str)) – User, group, or organization IDs that can read
this product.
Each ID must be prefixed with
user:
,group:
, ororg:
. - writers (list(str)) – User, group, or organization IDs that can edit
this product.
Each ID must be prefixed with
user:
,group:
, ororg:
. - name (str) – (Deprecated) Will be removed completely in future versions.
Return type: Returns: Replaced vector product, as a JSON API resource object. For a description of the keys, please see
get_product()
.Raises: - BadRequestError – Raised when the request is malformed, e.g. the owners list is missing prefixes.
- NotFoundError – Raised if the product cannot be found.
- RateLimitError – Raised when too many requests have been made within a given time period.
- ServerError – Raised when a unknown error occurred on the server.
-
search_features
(product_id, geometry=None, query_expr=None, query_limit=None, **kwargs)[source]¶ Iterate over vector features within an existing product.
At least one of
geometry
,query_expr
, orquery_limit
is required.The returned iterator has a length that indicates the size of the query.
Parameters: - product_id (str) – (Required) The ID of the product within which to search.
- geometry (dict) –
Search for Features intersecting this shape. This accepts the following types of GeoJSON or Shapely geometries:
- Points
- MultiPoints
- Polygons
- MultiPolygons
- LineStrings
- MultiLineStrings
- GeometryCollections
- query_expr (Expression) – Expression used to filter features by their properties, built from
dl.properties
. You can construct filter expression using the==
,!=
,<
,>
,<=
and>=
operators as well as thelike()
andin_()
methods. You cannot use the boolean keywordsand
andor
because of Python language limitations; instead you can combine filter expressions with&
(boolean “and”) and|
(boolean “or”). Example (assumingfrom descarteslabs import properties as p
):query_expr=(p.temperature >= 50) & (p.hour_of_day > 18)
. More complex example:query_expr=(100 > p.temperature >= 50) | ((p.month != 10) & (p.day_of_month > 14))
. If you supply a property which doesn’t exist as part of the expression that comparison will evaluate toFalse
. - query_limit (int) – Maximum number of features to return for this query, defaults to all.
Return type: Iterator of
DotDict
instancesReturns: Features satisfying the query, as JSONAPI primary data objects. For a description of the keys, please refer to
create_feature()
under thedata
key.len()
can be used on the returned iterator to determine the query size.Raises: - BadRequestError – Raised when the request is malformed, e.g. the query limit is not a number.
- NotFoundError – Raised if the product cannot be found.
- RateLimitError – Raised when too many requests have been made within a given time period.
- ServerError – Raised when a unknown error occurred on the server.
-
update_product
(product_id, name=None, title=None, description=None, owners=None, readers=None, writers=None)[source]¶ Update a vector product in your catalog using the given parameters. If a parameter is not provided, it will not change. You cannot change the
product_id
.Parameters: - product_id (str) – (Required) The ID of the Vector product to update.
- name (str) – (Deprecated) Will be removed completely in future versions.
- title (str) – Official product title.
- description (str) – Information about the product, why it exists, and what it provides.
- owners (list(str)) – User, group, or organization IDs that own this product.
Each ID must be prefixed with
user:
,group:
, ororg:
. - readers (list(str)) – User, group, or organization IDs that can read
this product.
Each ID must be prefixed with
user:
,group:
, ororg:
. - writers (list(str)) – User, group, or organization IDs that can edit
this product.
Each ID must be prefixed with
user:
,group:
, ororg:
.
Return type: Returns: Updated vector product, as a JSON API resource object. For a description of the keys please see
get_product()
.Raises: - BadRequestError – Raised when the request is malformed, e.g. the owners list is missing prefixes.
- NotFoundError – Raised if the product cannot be found.
- RateLimitError – Raised when too many requests have been made within a given time period.
- ServerError – Raised when a unknown error occurred on the server.
-
upload_features
(file_ish, product_id, max_errors=0, fix_geometry='accept')[source]¶ Asynchonously upload a file or stream of Newline Delimited JSON features. Note that the file may not contain empty lines or lines containing anything but the feature (including e.g. a trailing comma), or such lines will cause errors.
It is recommended that the IOBase object is a byte-oriented (not text-oriented) object, although Python 3 allows
io.StringIO
to be used.This is an asynchronous operation and you can query for the status using
get_upload_result()
with the upload_id returned by this method.Parameters: - file_ish (str or io.IOBase) – an open
io.IOBase
object, or a path to the file to upload. - product_id (str) – (Required) The ID of the Vector product to which these features will belong.
- max_errors (int) – The maximum number of errors permitted before declaring failure.
- fix_geometry (str) – String specifying how to handle certain problem
geometries, including those which do not follow counter-clockwise
winding order (which is required by the GeoJSON spec but not many
popular tools). Allowed values are
reject
(reject invalid geometries with an error),fix
(correct invalid geometries if possible and use this corrected value when creating the feature), andaccept
(the default) which will correct the geometry for internal use but retain the original geometry in the results.
Return type: str
Returns: The upload id.
Raises: - NotFoundError – Raised if the product cannot be found.
- RateLimitError – Raised when too many requests have been made within a given time period.
- ServerError – Raised when a unknown error occurred on the server.
- file_ish (str or io.IOBase) – an open
-
SEARCH_PAGE_SIZE
= 1000¶
-
TIMEOUT
= (9.5, 60)¶
-
properties
= <descarteslabs.common.property_filtering.filtering.Properties object>¶