# Generated by the protocol buffer compiler. DO NOT EDIT!
# sources: unacast/catalog/v3/query.proto
# plugin: python-betterproto
# This file has been @generated
from dataclasses import dataclass
from typing import (
TYPE_CHECKING,
Dict,
List,
Optional,
)
import betterproto
import grpclib
from betterproto.grpc.grpclib_server import ServiceBase
from ... import unatype as __unatype__
if TYPE_CHECKING:
import grpclib.server
from betterproto.grpc.grpclib_client import MetadataLike
from grpclib.metadata import Deadline
[docs]
class TrimToPeriodOfExistence(betterproto.Enum):
UNSPECIFIED = 0
TRIM = 1
IGNORE = 2
[docs]
class OrderDirection(betterproto.Enum):
UNSPECIFIED = 0
ASC = 1
DESC = 2
@dataclass(eq=False, repr=False)
class ListRecordsRequest(betterproto.Message):
data_reference_name: str = betterproto.string_field(1)
"""
Data reference name
Required. The data reference to query.
Find data references you have access to with the ListDataReferences method or through the UI.
Example: "ml_visitation.foot_traffic_month"
"""
fields: List["Field"] = betterproto.message_field(2)
"""
Fields
Optional. If not specified, default fields will be returned.
Use DataReference methods or field_definitions in the response to see which fields are available.
Example: ["location_id", "visits_p50", "visits_sum"]
"""
filters: List["__unatype__.FilterClause"] = betterproto.message_field(3)
"""
Filters
Optional. If not specified, no filters will be applied.
Find fields and supported operators in field_definitions in the response or through use of DataReference methods.
Example: [{"field": "location_id", "operator": "==", "value": "222-222@8f2-tyn-49z"}]
"""
options: "Options" = betterproto.message_field(4)
"""
Options
Optional. If not specified, default options will be applied.
"""
billing_context: str = betterproto.string_field(13)
"""
Billing context
Optional. Only applicable in advanced cases when not using API key.
"""
page_size: int = betterproto.int32_field(14)
"""
Page size
Optional. Default is 100.
Max is 366. InvalidArgument error if exceeded.
"""
page_token: str = betterproto.string_field(15)
"""
Page token
Optional. Used to get the next page of results.
"""
@dataclass(eq=False, repr=False)
class ListRecordsResponse(betterproto.Message):
records: List["Record"] = betterproto.message_field(1)
"""
Records
Example: [ {"fields:{"location_id": "222-222@8f2-tyn-49z", "visits_p50": 100, "visits_sum": 1000}}]
"""
field_definitions: List["FieldDefinition"] = betterproto.message_field(2)
"""
Field definitions
Example: [{"name": "location_id", "type": "string", "description": "Location ID", "filters": {"supported_operators": ["==", "!=", "in", "not_in", "contains", "starts_with", "ends_with", "is_empty", "is_not_empty"]}}, {"name": "visits_p50", "type": "number", "description": "Median visits", "filters": {"supported_operators": ["<", "<=", ">", ">=", "==", "!=", "in", "not_in"]}}, {"name": "visits_sum", "type": "number", "description": "Total visits", "filters": {"supported_operators": ["<", "<=", ">", ">=", "==", "!=", "in", "not_in"]}}]
"""
next_page_token: str = betterproto.string_field(3)
"""
Next page token
Used as the page_token in the next request to get the next page of results.
If empty, there are no more results.
"""
total_size: int = betterproto.int64_field(4)
"""
Total size
The total number of records that match the query before pagination
"""
@dataclass(eq=False, repr=False)
class Record(betterproto.Message):
"""
Record
A record is a single row of data.
"""
fields: Dict[str, str] = betterproto.map_field(
1, betterproto.TYPE_STRING, betterproto.TYPE_STRING
)
"""
Fields
Map of field name to value. Field names are default, or what you specified in the fields parameter.
Any value is returned as a string, use field_definitions to see the type for each field for conversion.
Note: As this is a map, order of fields is not guaranteed. Use field_definitions to get the order.
Example: {"location_id": "222-222@8f2-tyn-49z", "visits_p50": 100, "visits_sum": 1000}
"""
@dataclass(eq=False, repr=False)
class FieldDefinition(betterproto.Message):
"""
Field definition
A field definition is a description of a field.
"""
name: str = betterproto.string_field(1)
"""
Name
This is the name of the field as it will be used in the response.
Example: "location_id"
"""
source_column: str = betterproto.string_field(2)
"""
Source column
This is the name of the column in the underlying data.
This is useful if you are using a data reference and want to know which column in the data reference to use.
The different types of source columns are:
- "feature": as in geographic feature, contains its ID, name and geometry.
- "observation_period": as in observation period, contains its start and end. Only relevant for metric data.
- "dimension": dimension breakdowns of a metric. Only relevant for metric data.
- "metric_value": value of a metric. Only relevant for metric data.
- "address_components": metadata about a feature. Has a performance cost if used in field or filter clause on metric data.
- "related_feature": same as feature, its presence means the metric describes a relationship between the feature and the related feature.
- "related_address_component": same as address_components, just for the related feature.
Examples: "feature.feature_id.value", "feature.feature_id.display_name", "feature.point.latitude", "observation_period.start.value"
"""
type: str = betterproto.string_field(3)
"""
Type
This is the type of the field.
Examples: "COLUMN_TYPE_STRING", "COLUMN_TYPE_INTEGER", "COLUMN_TYPE_FLOAT", "COLUMN_TYPE_BOOLEAN", "COLUMN_TYPE_DATE"
"""
description: str = betterproto.string_field(4)
"""
Description
This is the description of the field.
"""
filters: "FilterDefinition" = betterproto.message_field(5)
"""
Filters
This is the supported filter operators.
"""
example_value: str = betterproto.string_field(6)
"""
Example value
This is an example value of the field.
"""
included_by_default: bool = betterproto.bool_field(7)
"""
Included by default
This is whether the field is included by default.
Invoking the ListRecords method without specifying the fields parameter will return all fields that are included by default.
"""
@dataclass(eq=False, repr=False)
class FilterDefinition(betterproto.Message):
"""
Filter definition
A filter definition is a description of a filter.
"""
supported_operators: List[str] = betterproto.string_field(1)
"""
Supported operators
This is the filter operators supported for the field when used in a filter clause.
"""
@dataclass(eq=False, repr=False)
class Field(betterproto.Message):
"""
Field
A field is specification for referencing a field in a query.
"""
name: str = betterproto.string_field(1)
"""
Name
This is the name of the field.
"""
source: str = betterproto.string_field(2)
"""
Source
Optional. Only for advanced usage. For overriding which source column to use for the field value.
Examples: "feature.feature_id.value", "observation_period.start.value"
"""
@dataclass(eq=False, repr=False)
class GetDataReferenceRequest(betterproto.Message):
data_reference_name: str = betterproto.string_field(1)
"""
Data reference name
Example: "ml_visitation.foot_traffic_month"
"""
billing_context: str = betterproto.string_field(13)
"""
Billing context
Optional. Only applicable in advanced cases when not using API key.
"""
@dataclass(eq=False, repr=False)
class GetDataReferenceResponse(betterproto.Message):
data_reference: "DataReference" = betterproto.message_field(1)
"""Data reference"""
@dataclass(eq=False, repr=False)
class ListDataReferencesRequest(betterproto.Message):
billing_context: str = betterproto.string_field(13)
"""
Billing context
Optional. Only applicable in advanced cases when not using API key.
"""
@dataclass(eq=False, repr=False)
class ListDataReferencesResponse(betterproto.Message):
data_references: List["DataReference"] = betterproto.message_field(1)
"""
Data references
Only data references this account-id as defined by the billing_context on the request has access to will be returned.
"""
@dataclass(eq=False, repr=False)
class DataReference(betterproto.Message):
"""
Data reference
A data reference is a structured description of a dataset.
You can use it as a reference to find out which fields are available for querying, which filters are supported, etc.
"""
name: str = betterproto.string_field(1)
"""
Name
The name of the data reference. Use this as the reference name when querying on other methods.
The structure of the name is:
<data_product_name>.<dataset_name>
Example: "ml_visitation.foot_traffic_month"
"""
data_product_display_name: str = betterproto.string_field(2)
"""
Data product display name
Human readable name of the data product this dataset belongs to.
Example: "Neighborhood Visitation"
"""
data_product_description: str = betterproto.string_field(3)
"""
Data product description
Description of the data product this dataset belongs to.
"""
data_listing_display_name: str = betterproto.string_field(4)
"""
Data listing display name
Human readable name of the dataset.
Example: "Foot Traffic Week"
"""
data_listing_description: str = betterproto.string_field(5)
"""
Data listing description
Description of the dataset.
"""
fields: List["FieldDefinition"] = betterproto.message_field(6)
"""
Fields
All fields available for querying on this dataset.
"""
options: "OptionDefinitions" = betterproto.message_field(7)
"""
Supported options
All options and if they are available for this dataset.
"""
date_range: "__unatype__.DateRange" = betterproto.message_field(8)
"""
Date range
Available date range of the dataset.
"""
@dataclass(eq=False, repr=False)
class Options(betterproto.Message):
"""Options"""
bounding_box: "BoundingBox" = betterproto.message_field(1)
"""
Bounding box
Optional. Only returns records with its feature point within the bounding box.
"""
trim_to_period_of_existence: "TrimToPeriodOfExistence" = betterproto.enum_field(2)
"""
Trim to period of existence
Optional. Only returns records within the period of existence of the feature.
Default behaviour is to TRIM.
Example: A feature has existed from 2020-01-01 to 2020-01-05.
If TRIM is specified, only records from 2020-01-01 to 2020-01-05 are returned.
If IGNORE is specified, all records are returned, but only the period of existence of the feature is considered when evaluating other filters.
"""
order_by: "OrderBy" = betterproto.message_field(3)
"""
Order by
Optional. Order the results by a field.
"""
@dataclass(eq=False, repr=False)
class OptionDefinitions(betterproto.Message):
"""Option definitions"""
bounding_box: "BoundingBoxDefinition" = betterproto.message_field(1)
"""
Bounding box
Description of the bounding box filter.
"""
trim_to_period_of_existence: "TrimToPeriodOfExistenceDefinition" = (
betterproto.message_field(2)
)
"""
Trim to period of existence definition
Description of the trim to period of existence filter.
"""
order_by: "OrderByDefinition" = betterproto.message_field(3)
"""
Order by definition
Description of the order by option.
"""
@dataclass(eq=False, repr=False)
class TrimToPeriodOfExistenceDefinition(betterproto.Message):
example_value: "TrimToPeriodOfExistence" = betterproto.enum_field(1)
"""Example value"""
display_name: str = betterproto.string_field(2)
"""Display name"""
description: str = betterproto.string_field(3)
"""Description"""
available: bool = betterproto.bool_field(4)
"""
Available
Whether the option is available for this dataset.
"""
[docs]
@dataclass(eq=False, repr=False)
class OrderBy(betterproto.Message):
field_name: str = betterproto.string_field(1)
"""
Field name
The field to order by.
"""
direction: "OrderDirection" = betterproto.enum_field(2)
"""
Direction
The direction to order by.
Default is ASCENDING.
"""
@dataclass(eq=False, repr=False)
class OrderByDefinition(betterproto.Message):
example_value: "OrderBy" = betterproto.message_field(1)
"""Example value"""
display_name: str = betterproto.string_field(2)
"""Display name"""
description: str = betterproto.string_field(3)
"""Description"""
available: bool = betterproto.bool_field(4)
"""
Available
Whether the option is available for this dataset.
"""
[docs]
@dataclass(eq=False, repr=False)
class BoundingBox(betterproto.Message):
"""
Bounding box
Example: {"minLng": -74.006, "minLat": 40.7128, "maxLng": -73.998, "maxLat": 40.708}
"""
min_lng: float = betterproto.double_field(1)
"""
minLng
The westmost constant longitude line that bounds the rectangle
"""
min_lat: float = betterproto.double_field(2)
"""
minLat
The minimum constant latitude line that bounds the rectangle
"""
max_lng: float = betterproto.double_field(3)
"""
maxLng
The eastmost constant longitude line that bounds the rectangle
"""
max_lat: float = betterproto.double_field(4)
"""
maxLat
The maximum constant latitude line that bounds the rectangle
"""
@dataclass(eq=False, repr=False)
class BoundingBoxDefinition(betterproto.Message):
"""Bounding box definition"""
example_value: "BoundingBox" = betterproto.message_field(1)
"""Example value"""
display_name: str = betterproto.string_field(2)
"""Display name"""
description: str = betterproto.string_field(3)
"""Description"""
available: bool = betterproto.bool_field(4)
"""
Available
Whether the option is available for this dataset.
"""
@dataclass(eq=False, repr=False)
class SearchFieldValuesRequest(betterproto.Message):
data_reference_name: str = betterproto.string_field(1)
"""
Data reference name
Required. The data reference to search field values on.
Example: "ml_visitation.foot_traffic_month"
"""
field: "Field" = betterproto.message_field(2)
"""
Field
Required. The field to search for distinct values on.
Example: "city"
"""
term: str = betterproto.string_field(3)
"""
Term
Optional. The search term to filter distinct values on.
Example: "Boul" for "Boulder"
"""
filters: List["__unatype__.FilterClause"] = betterproto.message_field(4)
"""
Filters
Optional. If not specified, no filters will be applied.
Search will be limited to the values that match all filters.
"""
options: "Options" = betterproto.message_field(5)
"""
Options
Optional. If not specified, no options will be applied.
"""
billing_context: str = betterproto.string_field(13)
"""
Billing context
Optional. Only applicable in advanced cases when not using API key.
"""
page_size: int = betterproto.int32_field(14)
"""
Page size
Optional. Default is 100, max is 10000.
"""
page_token: str = betterproto.string_field(15)
"""
Page token
Optional. Used to get the next page of results.
"""
@dataclass(eq=False, repr=False)
class SearchFieldValuesResponse(betterproto.Message):
values: List[str] = betterproto.string_field(1)
"""
Values
Example: ["Boulder", "Denver", "San Francisco"]
"""
field_definition: "FieldDefinition" = betterproto.message_field(2)
"""
Field definition
Definition of the field the values belong to.
Example: {"name": "city", "type": "string", "description": "City", "filters": {"supported_operators": ["==", "!=", "in", "not_in", "contains", "starts_with", "ends_with", "is_empty", "is_not_empty"]}}
"""
next_page_token: str = betterproto.string_field(3)
"""
Next page token
Used as the page_token in the next request to get the next page of results.
If empty, there are no more results.
"""
class CatalogQueryStub(betterproto.ServiceStub):
async def list_records(
self,
list_records_request: "ListRecordsRequest",
*,
timeout: Optional[float] = None,
deadline: Optional["Deadline"] = None,
metadata: Optional["MetadataLike"] = None
) -> "ListRecordsResponse":
return await self._unary_unary(
"/unacast.catalog.v3.CatalogQuery/ListRecords",
list_records_request,
ListRecordsResponse,
timeout=timeout,
deadline=deadline,
metadata=metadata,
)
async def list_data_references(
self,
list_data_references_request: "ListDataReferencesRequest",
*,
timeout: Optional[float] = None,
deadline: Optional["Deadline"] = None,
metadata: Optional["MetadataLike"] = None
) -> "ListDataReferencesResponse":
return await self._unary_unary(
"/unacast.catalog.v3.CatalogQuery/ListDataReferences",
list_data_references_request,
ListDataReferencesResponse,
timeout=timeout,
deadline=deadline,
metadata=metadata,
)
async def get_data_reference(
self,
get_data_reference_request: "GetDataReferenceRequest",
*,
timeout: Optional[float] = None,
deadline: Optional["Deadline"] = None,
metadata: Optional["MetadataLike"] = None
) -> "GetDataReferenceResponse":
return await self._unary_unary(
"/unacast.catalog.v3.CatalogQuery/GetDataReference",
get_data_reference_request,
GetDataReferenceResponse,
timeout=timeout,
deadline=deadline,
metadata=metadata,
)
async def search_field_values(
self,
search_field_values_request: "SearchFieldValuesRequest",
*,
timeout: Optional[float] = None,
deadline: Optional["Deadline"] = None,
metadata: Optional["MetadataLike"] = None
) -> "SearchFieldValuesResponse":
return await self._unary_unary(
"/unacast.catalog.v3.CatalogQuery/SearchFieldValues",
search_field_values_request,
SearchFieldValuesResponse,
timeout=timeout,
deadline=deadline,
metadata=metadata,
)
class CatalogQueryBase(ServiceBase):
async def list_records(
self, list_records_request: "ListRecordsRequest"
) -> "ListRecordsResponse":
raise grpclib.GRPCError(grpclib.const.Status.UNIMPLEMENTED)
async def list_data_references(
self, list_data_references_request: "ListDataReferencesRequest"
) -> "ListDataReferencesResponse":
raise grpclib.GRPCError(grpclib.const.Status.UNIMPLEMENTED)
async def get_data_reference(
self, get_data_reference_request: "GetDataReferenceRequest"
) -> "GetDataReferenceResponse":
raise grpclib.GRPCError(grpclib.const.Status.UNIMPLEMENTED)
async def search_field_values(
self, search_field_values_request: "SearchFieldValuesRequest"
) -> "SearchFieldValuesResponse":
raise grpclib.GRPCError(grpclib.const.Status.UNIMPLEMENTED)
async def __rpc_list_records(
self, stream: "grpclib.server.Stream[ListRecordsRequest, ListRecordsResponse]"
) -> None:
request = await stream.recv_message()
response = await self.list_records(request)
await stream.send_message(response)
async def __rpc_list_data_references(
self,
stream: "grpclib.server.Stream[ListDataReferencesRequest, ListDataReferencesResponse]",
) -> None:
request = await stream.recv_message()
response = await self.list_data_references(request)
await stream.send_message(response)
async def __rpc_get_data_reference(
self,
stream: "grpclib.server.Stream[GetDataReferenceRequest, GetDataReferenceResponse]",
) -> None:
request = await stream.recv_message()
response = await self.get_data_reference(request)
await stream.send_message(response)
async def __rpc_search_field_values(
self,
stream: "grpclib.server.Stream[SearchFieldValuesRequest, SearchFieldValuesResponse]",
) -> None:
request = await stream.recv_message()
response = await self.search_field_values(request)
await stream.send_message(response)
def __mapping__(self) -> Dict[str, grpclib.const.Handler]:
return {
"/unacast.catalog.v3.CatalogQuery/ListRecords": grpclib.const.Handler(
self.__rpc_list_records,
grpclib.const.Cardinality.UNARY_UNARY,
ListRecordsRequest,
ListRecordsResponse,
),
"/unacast.catalog.v3.CatalogQuery/ListDataReferences": grpclib.const.Handler(
self.__rpc_list_data_references,
grpclib.const.Cardinality.UNARY_UNARY,
ListDataReferencesRequest,
ListDataReferencesResponse,
),
"/unacast.catalog.v3.CatalogQuery/GetDataReference": grpclib.const.Handler(
self.__rpc_get_data_reference,
grpclib.const.Cardinality.UNARY_UNARY,
GetDataReferenceRequest,
GetDataReferenceResponse,
),
"/unacast.catalog.v3.CatalogQuery/SearchFieldValues": grpclib.const.Handler(
self.__rpc_search_field_values,
grpclib.const.Cardinality.UNARY_UNARY,
SearchFieldValuesRequest,
SearchFieldValuesResponse,
),
}