Vector

Note: It is recommended to use the object oriented interface at descarteslabs.vectors.

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 name, description, and access controls.

This client currently returns data as dictionaries in JSON API format.

The parent Service class implements authentication and exponential backoff/retry. Override the url parameter to use a different instance of the backing service.

create_feature(product_id, geometry, properties=None)[source]

Add a feature to an existing vector product.

Parameters:
  • product_id (str) – (Required) Product to which this feature will belong.
  • geometry (dict) – (Required) Shape associated with this vector feature. This accepts the following types of GeoJSON geometries: - Points - MultiPoints - Polygons - MultiPolygons - LineStrings - MultiLineStrings - GeometryCollections
  • properties (dict) – Dictionary of arbitrary properties.
Return type:

DotDict
Returns:

Created Feature, as a JSON API resource collection.

The new Feature’s ID is under .data[0].id, and its properties are under .data[0].attributes.
create_features(product_id, features)[source]

Add multiple features to an existing vector product.

Parameters:
  • product_id (str) – (Required) Product to which this feature will belong.
  • features (list(dict)) – (Required) Each feature must be a dict with a geometry and properties field. If more than 100 features, will be batched in groups of 100, but consider using upload_features() instead.
Return type:

DotDict
Returns:

Created features, as a JSON API resource collection.

The new Features’ IDs are under .data[i].id, and their properties are under .data[i].attributes.
Raises:

ClientError – A variety of http-related exceptions can thrown. If more than 100 features were passed in, some of these may have been successfully inserted, others not. If this is a problem, then stick with <= 100 features.
create_product(name, title, description, owners=None, readers=None, writers=None)[source]

Add a vector product to your catalog.

Parameters:
  • name (str) – (Required) A name for this product.
  • title (str) – (Required) Official product title.
  • description (str) – (Required) Information about the product, why it exists, and what it provides.
Param:

list(str) owners: User, group, or organization IDs that own this product. Each ID must be prefixed with user:, group:, or org:. Defaults to [current user, current user’s org].
Param:

list(str) readers: User, group, or organization IDs that can read this product. Each ID must be prefixed with user:, group:, or org:.
Param:

list(str) writers: User, group, or organization IDs that can edit this product. Each ID must be prefixed with user:, group:, or org:.
Return type:

DotDict
Returns:

Created vector product, as a JSON API resource object.

The new product’s ID is under .data.id and its properties are under .data.attributes.
create_product_from_query(name, 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, or query_limit is required.

Parameters:
  • name (str) – (Required) A name for the new product.
  • title (str) – (Required) Official product title.
  • description (str) – (Required) Information about the product, why it exists, and what it provides.
  • product_id (str) – (Required) Product within which to search.
  • geometry (dict) –

    Search for Features intersecting this shape. This accepts the following types of GeoJSON geometries:

    • Points
    • MultiPoints
    • Polygons
    • MultiPolygons
    • LineStrings
    • MultiLineStrings
    • GeometryCollections
  • query_expr (descarteslabs.client.common.filtering.Expression) – A rich query expression generator that represents an arbitrary tree of boolean combinations of property comparisons. Using the properties filter factory inside descarteslabs.client.services.vector.properties as p, you can E.g query_expr=(p.temperature >= 50) & (p.hour_of_day > 18), or even more complicated expressions like query_expr=(100 > p.temperature >= 50) | ((p.month != 10) & (p.day_of_month > 14)) This expression gets serialized and applied to the properties mapping supplied with the features in the vector product. If you supply a property which doesn’t exist as part of the expression that comparison will evaluate to False.
  • query_limit (int) – Maximum number of features to return for this query, defaults to all.
Param:

list(str) owners: User, group, or organization IDs that own this product. Each ID must be prefixed with user:, group:, or org:. Defaults to [current user, current user’s org].
Param:

list(str) readers: User, group, or organization IDs that can read this product. Each ID must be prefixed with user:, group:, or org:.
Param:

list(str) writers: User, group, or organization IDs that can edit this product. Each ID must be prefixed with user:, group:, or org:.
Return type:

DotDict
Returns:

Created vector product, as a JSON API resource object.

The new product’s ID is under .data.id and its properties are under .data.attributes.
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.

At least one of geometry, query_expr, or properties is required.

Parameters:
  • product_id (str) – (Required) Product within which to search for features to delete.
  • geometry (dict) –

    Search for Features intersecting this shape. This accepts the following types of GeoJSON geometries:

    • Points
    • MultiPoints
    • Polygons
    • MultiPolygons
    • LineStrings
    • MultiLineStrings
    • GeometryCollections
  • query_expr (descarteslabs.client.common.filtering.Expression) – A rich query expression generator that represents an arbitrary tree of boolean combinations of property comparisons. Using the properties filter factory inside descarteslabs.client.services.vector.properties as p, you can E.g query_expr=(p.temperature >= 50) & (p.hour_of_day > 18), or even more complicated expressions like query_expr=(100 > p.temperature >= 50) | ((p.month != 10) & (p.day_of_month > 14)) This expression gets serialized and applied to the properties mapping supplied with the features in the vector product. If you supply a property which doesn’t exist as part of the expression that comparison will evaluate to False.
Return type:

DotDict
Returns:

The Vector product features were deleted from, as a JSON API resource object.

The new product’s ID is under .data.id and its properties are under .data.attributes.
delete_product(product_id)[source]

Remove a vector product from the catalog.

Parameters:product_id (str) – ID of the vector product to remove.
get_delete_features_status(product_id)[source]

Get the status of the job deleting features from a query.

Parameters:product_id (str) – (Required) Id of the product created by a call to create_product_from_query.
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:DotDict
Returns:Metadata for the provided product, as a JSON API resource object.

The product’s ID is under .data.id and its properties are under .data.attributes.
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) Id of the product created by a call to create_product_from_query.
get_upload_result(product_id, upload_id)[source]

Get details about a specific upload job. Included information about processing error streams, which can help debug failed uploads.

Parameters:
get_upload_results(product_id)[source]

Get a list of the uploads submitted to a vector product, and status information about each.

Parameters:product_id (str) – (required)
Returns:An iterator over all upload resources created with Vector.upload_features()
Return type:Iterator
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:

DotDict
Returns:

Available vector products and their properties, as a JSON API collection.

The list of products is under the data key; a product’s ID is under .data[i].id and its properties are under .data[i].attributes.
replace_product(product_id, name, title, description, owners=None, readers=None, writers=None)[source]

Replace a vector product in your catalog.

Parameters:
  • product_id (str) – (Required) The vector product to replace.
  • name (str) – (Required) A name for this product.
  • title (str) – (Required) Official product title.
  • description (str) – (Required) Information about the product, why it exists, and what it provides.
Param:

list(str) owners: User, group, or organization IDs that own this product. Each ID must be prefixed with user:, group:, or org:. Defaults to [current user, current user’s org].
Param:

list(str) readers: User, group, or organization IDs that can read this product. Each ID must be prefixed with user:, group:, or org:.
Param:

list(str) writers: User, group, or organization IDs that can edit this product. Each ID must be prefixed with user:, group:, or org:.
Return type:

DotDict
Returns:

Replaced vector product, as a JSON API resource object

The new product’s ID is under .data.id and its properties are under .data.attributes.
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, or properties is required.

The returned iterator has a length that indicates the size of the query.

Parameters:
  • product_id (str) – (Required) Product within which to search.
  • geometry (dict) –

    Search for Features intersecting this shape. This accepts the following types of GeoJSON geometries:

    • Points
    • MultiPoints
    • Polygons
    • MultiPolygons
    • LineStrings
    • MultiLineStrings
    • GeometryCollections
  • query_expr (descarteslabs.client.common.filtering.Expression) – A rich query expression generator that represents an arbitrary tree of boolean combinations of property comparisons. Using the properties filter factory inside descarteslabs.client.services.vector.properties as p, you can E.g query_expr=(p.temperature >= 50) & (p.hour_of_day > 18), or even more complicated expressions like query_expr=(100 > p.temperature >= 50) | ((p.month != 10) & (p.day_of_month > 14)) This expression gets serialized and applied to the properties mapping supplied with the features in the vector product. If you supply a property which doesn’t exist as part of the expression that comparison will evaluate to False.
  • query_limit (int) – Maximum number of features to return for this query, defaults to all.
Return type:

Iterator
Returns:

Features satisfying the query, as JSONAPI primary data objects.

The Features’ IDs are under .id, and their properties are under .attributes. len() can be used on the returned iterator to determine the query size.
update_product(product_id, name=None, title=None, description=None, owners=None, readers=None, writers=None)[source]

Update a vector product in your catalog.

Parameters:
  • product_id (str) – (Required) The vector product to replace.
  • name (str) – Name for this product.
  • title (str) – Official product title.
  • description (str) – Information about the product, why it exists, and what it provides.
Param:

list(str) owners: User, group, or organization IDs that own this product. Each ID must be prefixed with user:, group:, or org:.
Param:

list(str) readers: User, group, or organization IDs that can read this product. Each ID must be prefixed with user:, group:, or org:.
Param:

list(str) writers: User, group, or organization IDs that can edit this product. Each ID must be prefixed with user:, group:, or org:.
Returns:

Updated vector product, as a JSON API resource object.
Return type:

DotDict
upload_features(file_ish, product_id, max_errors=0)[source]

Asynchonously upload a file or stream of Newline Delimited JSON features.

It is recommended that the IOBase object is a byte-oriented (not text-oriented) object, although Python 3 allows io.StringIO to be used.

:param str|:py:class:io.IOBase file_ish: an open IOBase object, or a path to the file to upload. :param str product_id: Product to which these features will belong. :param int max_errors: The maximum number of errors permitted before declaring failure.

SEARCH_PAGE_SIZE = 1000
TIMEOUT = (9.5, 60)
properties = <descarteslabs.common.property_filtering.filtering.GenericProperties object>