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:

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

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:

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

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.

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.

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

delete_product(product_id)[source]¶

Remove a vector product from the catalog.

Parameters:	product_id (str) – ID of the vector product to remove.

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_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:	product_id (str) – (required) upload_id (str) – (required) An id pertaining to this requested upload, either returned by `Vector.get_upload_results()` or `Vector.upload_features()`.

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:

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

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.

Parameters:

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

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.

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)[source]¶

Asynchonously upload a file of Newline Delimited JSON features.

:param str|:py:class:io.IOBase file_ish: an open file object, or a path to the file to upload. :param str product_id: Product to which these features will belong.

SEARCH_PAGE_SIZE = 1000¶

TIMEOUT = (9.5, 60)¶

properties = <descarteslabs.common.property_filtering.filtering.GenericProperties object>¶

Table Of Contents

Links

Vector¶