diff --git a/cognite/client/data_classes/filters.py b/cognite/client/data_classes/filters.py index bc2ccc8561..3e6b886c85 100644 --- a/cognite/client/data_classes/filters.py +++ b/cognite/client/data_classes/filters.py @@ -251,16 +251,56 @@ def _filter_body(self, camel_case_property: bool) -> dict[str, Any]: @final class And(CompoundFilter): + """A filter that combines multiple filters with a logical AND. + + Args: + *filters (Filter): The filters to combine. + + + Example: + + Combine an In and an Equals filter:: + + >>> from cognite.client.data_classes.filters import And, Equals, In + >>> filter = And(Equals(("some", "property"), 42), In(("another", "property"), ["a", "b", "c"])) + """ + _filter_name = "and" @final class Or(CompoundFilter): + """A filter that combines multiple filters with a logical OR. + + Args: + *filters (Filter): The filters to combine. + + Example: + + Combine an In and an Equals filter:: + + >>> from cognite.client.data_classes.filters import Or, Equals, In + >>> filter = Or(Equals(("some", "property"), 42), In(("another", "property"), ["a", "b", "c"])) + """ + _filter_name = "or" @final class Not(CompoundFilter): + """A filter that negates another filter. + + Args: + filter (Filter): The filter to negate. + + Example: + + Negate an Equals filter: + + >>> from cognite.client.data_classes.filters import Or, Equals + >>> filter = Not(Equals(("some", "property"), 42)) + """ + _filter_name = "not" def __init__(self, filter: Filter) -> None: @@ -272,6 +312,23 @@ def _filter_body(self, camel_case_property: bool) -> dict: @final class Nested(Filter): + """A filter to apply to the node at the other side of a direct relation. + + Args: + scope (PropertyReference): The direct relation property to traverse. + filter (Filter): The filter to apply. + + Example: + + Filter on a related node's property: + + >>> from cognite.client.data_classes.filters import Nested, Equals + >>> filter = Nested( + ... ("somespace", "somecontainer", "related"), + ... Equals(("somespace", "somecontainer", "someProperty"), 42) + ... ) + """ + _filter_name = "nested" def __init__(self, scope: PropertyReference, filter: Filter) -> None: @@ -284,6 +341,16 @@ def _filter_body(self, camel_case_property: bool) -> dict[str, Any]: @final class MatchAll(Filter): + """A filter that matches all instances. + + Example: + + Match everything: + + >>> from cognite.client.data_classes.filters import MatchAll + >>> filter = MatchAll() + """ + _filter_name = "matchAll" def _filter_body(self, camel_case_property: bool) -> dict[str, Any]: @@ -292,6 +359,20 @@ def _filter_body(self, camel_case_property: bool) -> dict[str, Any]: @final class HasData(Filter): + """Return only instances that have data in the provided containers/views. + + Args: + containers (Sequence[tuple[str, str] | ContainerId] | None): Containers to check for data. + views (Sequence[tuple[str, str, str] | ViewId] | None): Views to check for data. + + Example: + + Filter on having data in a specific container: + + >>> from cognite.client.data_classes.filters import HasData + >>> filter = HasData(containers=[("somespace", "somecontainer")]) + """ + _filter_name = "hasData" def __init__( @@ -319,6 +400,23 @@ def _filter_body(self, camel_case_property: bool) -> list: @final class Range(FilterWithProperty): + """Filters results based on a range of values. + + Args: + property (PropertyReference): The property to filter on. + gt (FilterValue | None): Greater than. + gte (FilterValue | None): Greater than or equal to. + lt (FilterValue | None): Less than. + lte (FilterValue | None): Less than or equal to. + + Example: + + Retrieve all instances with a property value greater than 42: + + >>> from cognite.client.data_classes.filters import Range + >>> filter = Range(("some", "property"), gt=42) + """ + _filter_name = "range" def __init__( @@ -350,6 +448,26 @@ def _filter_body(self, camel_case_property: bool) -> dict[str, Any]: @final class Overlaps(Filter): + """Filters results based whether or not the provided range overlaps with the range given by the start and end + properties. + + Args: + start_property (PropertyReference): The property to filter on. + end_property (PropertyReference): The property to filter on. + gt (FilterValue | None): Greater than. + gte (FilterValue | None): Greater than or equal to. + lt (FilterValue | None): Less than. + lte (FilterValue | None): Less than or equal to. + + + Example: + + Retrieve all instances with a range overlapping with the range (42, 100): + + >>> from cognite.client.data_classes.filters import Overlaps + >>> filter = Overlaps(("some", "startProperty"), ("some", "endProperty"), gt=42, lt=100) + """ + _filter_name = "overlaps" def __init__( @@ -387,31 +505,114 @@ def _filter_body(self, camel_case_property: bool) -> dict[str, Any]: @final class Equals(FilterWithPropertyAndValue): + """Filters results based on whether the property equals the provided value. + + Args: + property (PropertyReference): The property to filter on. + value (FilterValue): The value to filter on. + + Example: + + Filter than can be used to retrieve items where the property value equals 42: + + >>> from cognite.client.data_classes.filters import Equals + >>> filter = Equals(("some", "property"), 42) + """ + _filter_name = "equals" @final class In(FilterWithPropertyAndValueList): + """Filters results based on whether the property equals one of the provided values. + + Args: + property (PropertyReference): The property to filter on. + values (FilterValueList): The values to filter on. + + Example: + + Filter than can be used to retrieve items where the property value equals 42 or 43 (or both): + + >>> from cognite.client.data_classes.filters import In + >>> filter = In(("some", "property"), [42, 43]) + """ + _filter_name = "in" @final class Exists(FilterWithProperty): + """Filters results based on whether the property is set or not. + + Args: + property (PropertyReference): The property to filter on. + + Example: + + Filter than can be used to retrieve items where the property value is set: + + >>> from cognite.client.data_classes.filters import Exists + >>> filter = Exists(("some", "property")) + """ + _filter_name = "exists" @final class Prefix(FilterWithPropertyAndValue): + """Prefix filter results based on whether the (text) property starts with the provided value. + + Args: + property (PropertyReference): The property to filter on. + value (FilterValue): The value to filter on. + + Example: + + Filter than can be used to retrieve items where the property value starts with "somePrefix": + + >>> from cognite.client.data_classes.filters import Prefix + >>> filter = Prefix(("some", "property"), "somePrefix") + """ + _filter_name = "prefix" @final class ContainsAny(FilterWithPropertyAndValueList): + """Returns results where the referenced property contains _any_ of the provided values. + + Args: + property (PropertyReference): The property to filter on. + values (FilterValueList): The value to filter on. + + Example: + + Filter than can be used to retrieve items where the property value contains either 42 or 43: + + >>> from cognite.client.data_classes.filters import ContainsAny + >>> filter = ContainsAny(("some", "property"), [42, 43]) + """ + _filter_name = "containsAny" @final class ContainsAll(FilterWithPropertyAndValueList): + """Returns results where the referenced property contains _all_ of the provided values. + + Args: + property (PropertyReference): The property to filter on. + values (FilterValueList): The value to filter on. + + Example: + + Filter than can be used to retrieve items where the property value contains both 42 and 43: + + >>> from cognite.client.data_classes.filters import ContainsAll + >>> filter = ContainsAll(("some", "property"), [42, 43]) + """ + _filter_name = "containsAll" diff --git a/docs/source/assets.rst b/docs/source/assets.rst new file mode 100644 index 0000000000..ca837bf347 --- /dev/null +++ b/docs/source/assets.rst @@ -0,0 +1,75 @@ +Assets +====== +Retrieve an asset by id +^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.assets.AssetsAPI.retrieve + +Retrieve multiple assets by id +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.assets.AssetsAPI.retrieve_multiple + +Retrieve an asset subtree +^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.assets.AssetsAPI.retrieve_subtree + +List assets +^^^^^^^^^^^ +.. automethod:: cognite.client._api.assets.AssetsAPI.list + +Aggregate assets +^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.assets.AssetsAPI.aggregate + +Aggregate Asset Count +^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.assets.AssetsAPI.aggregate_count + +Aggregate Asset Value Cardinality +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.assets.AssetsAPI.aggregate_cardinality_values + +Aggregate Asset Property Cardinality +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.assets.AssetsAPI.aggregate_cardinality_properties + +Aggregate Asset Unique Values +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.assets.AssetsAPI.aggregate_unique_values + +Aggregate Asset Unique Properties +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.assets.AssetsAPI.aggregate_unique_properties + +Search for assets +^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.assets.AssetsAPI.search + +Create assets +^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.assets.AssetsAPI.create + +Create asset hierarchy +^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.assets.AssetsAPI.create_hierarchy + +Delete assets +^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.assets.AssetsAPI.delete + +Filter assets +^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.assets.AssetsAPI.filter + +Update assets +^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.assets.AssetsAPI.update + +Upsert assets +^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.assets.AssetsAPI.upsert + +Asset Data classes +^^^^^^^^^^^^^^^^^^ +.. automodule:: cognite.client.data_classes.assets + :members: + :show-inheritance: diff --git a/docs/source/core_data_model.rst b/docs/source/core_data_model.rst deleted file mode 100644 index 8c2e062405..0000000000 --- a/docs/source/core_data_model.rst +++ /dev/null @@ -1,596 +0,0 @@ -Core Data Model -=============== -Assets ------- -Retrieve an asset by id -^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.assets.AssetsAPI.retrieve - -Retrieve multiple assets by id -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.assets.AssetsAPI.retrieve_multiple - -Retrieve an asset subtree -^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.assets.AssetsAPI.retrieve_subtree - -List assets -^^^^^^^^^^^ -.. automethod:: cognite.client._api.assets.AssetsAPI.list - -Aggregate assets -^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.assets.AssetsAPI.aggregate - -Aggregate Asset Count -^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.assets.AssetsAPI.aggregate_count - -Aggregate Asset Value Cardinality -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.assets.AssetsAPI.aggregate_cardinality_values - -Aggregate Asset Property Cardinality -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.assets.AssetsAPI.aggregate_cardinality_properties - -Aggregate Asset Unique Values -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.assets.AssetsAPI.aggregate_unique_values - -Aggregate Asset Unique Properties -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.assets.AssetsAPI.aggregate_unique_properties - -Search for assets -^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.assets.AssetsAPI.search - -Create assets -^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.assets.AssetsAPI.create - -Create asset hierarchy -^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.assets.AssetsAPI.create_hierarchy - -Delete assets -^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.assets.AssetsAPI.delete - -Filter assets -^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.assets.AssetsAPI.filter - -Update assets -^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.assets.AssetsAPI.update - -Upsert assets -^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.assets.AssetsAPI.upsert - -Asset Data classes -^^^^^^^^^^^^^^^^^^ -.. automodule:: cognite.client.data_classes.assets - :members: - :show-inheritance: - -Events ------- -Retrieve an event by id -^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.events.EventsAPI.retrieve - -Retrieve multiple events by id -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.events.EventsAPI.retrieve_multiple - -List events -^^^^^^^^^^^ -.. automethod:: cognite.client._api.events.EventsAPI.list - -Aggregate events -^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.events.EventsAPI.aggregate - -Aggregate Event Count -^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.events.EventsAPI.aggregate_count - -Aggregate Event Values Cardinality -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.events.EventsAPI.aggregate_cardinality_values - -Aggregate Event Property Cardinality -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.events.EventsAPI.aggregate_cardinality_properties - -Aggregate Event Unique Values -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.events.EventsAPI.aggregate_unique_values - -Aggregate Event Unique Properties -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.events.EventsAPI.aggregate_unique_properties - -Search for events -^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.events.EventsAPI.search - -Create events -^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.events.EventsAPI.create - -Delete events -^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.events.EventsAPI.delete - -Update events -^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.events.EventsAPI.update - -Upsert events -^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.events.EventsAPI.upsert - -Filter events -^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.events.EventsAPI.filter - -Events Data classes -^^^^^^^^^^^^^^^^^^^ -.. automodule:: cognite.client.data_classes.events - :members: - :show-inheritance: - -Data points ------------ -.. warning:: - TimeSeries unit support is a new feature: - * The API specification is in beta. - * The SDK implementation is in alpha. - - Unit conversion is implemented in the Datapoints APIs with the parameters `target_unit` and `target_unit_system` in - the retrieve methods below. It is only the use of these arguments that is in alpha. Using the methods below - without these arguments is stable. - - Thus, breaking changes may occur without further notice, see :ref:`appendix-alpha-beta-features` for more information. - - -Retrieve datapoints -^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.datapoints.DatapointsAPI.retrieve - -Retrieve datapoints as numpy arrays -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.datapoints.DatapointsAPI.retrieve_arrays - -Retrieve datapoints in pandas dataframe -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.datapoints.DatapointsAPI.retrieve_dataframe - -Retrieve datapoints in time zone in pandas dataframe -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.datapoints.DatapointsAPI.retrieve_dataframe_in_tz - -Retrieve latest datapoint -^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.datapoints.DatapointsAPI.retrieve_latest - -Insert data points -^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.datapoints.DatapointsAPI.insert - -Insert data points into multiple time series -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.datapoints.DatapointsAPI.insert_multiple - -Insert pandas dataframe -^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.datapoints.DatapointsAPI.insert_dataframe - -Delete a range of data points -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.datapoints.DatapointsAPI.delete_range - -Delete ranges of data points -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.datapoints.DatapointsAPI.delete_ranges - - -Data Points Data classes -^^^^^^^^^^^^^^^^^^^^^^^^ -.. automodule:: cognite.client.data_classes.datapoints - :members: - :show-inheritance: - -Files ------ -Retrieve file metadata by id -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.files.FilesAPI.retrieve - -Retrieve multiple files' metadata by id -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.files.FilesAPI.retrieve_multiple - -List files metadata -^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.files.FilesAPI.list - -Aggregate files metadata -^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.files.FilesAPI.aggregate - -Search for files -^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.files.FilesAPI.search - -Create file metadata -^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.files.FilesAPI.create - -Upload a file or directory -^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.files.FilesAPI.upload - -Upload a string or bytes -^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.files.FilesAPI.upload_bytes - -Retrieve download urls -^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.files.FilesAPI.retrieve_download_urls - -Download files to disk -^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.files.FilesAPI.download - -Download a single file to a specific path -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.files.FilesAPI.download_to_path - -Download a file as bytes -^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.files.FilesAPI.download_bytes - -Delete files -^^^^^^^^^^^^ -.. automethod:: cognite.client._api.files.FilesAPI.delete - -Update files metadata -^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.files.FilesAPI.update - -Files Data classes -^^^^^^^^^^^^^^^^^^ -.. automodule:: cognite.client.data_classes.files - :members: - :show-inheritance: - - - -Geospatial ----------- -.. note:: - Check https://github.com/cognitedata/geospatial-examples for some complete examples. - -Create feature types -^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.geospatial.GeospatialAPI.create_feature_types - -Delete feature types -^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.geospatial.GeospatialAPI.delete_feature_types - -List feature types -^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.geospatial.GeospatialAPI.list_feature_types - -Retrieve feature types -^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.geospatial.GeospatialAPI.retrieve_feature_types - -Update feature types -^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.geospatial.GeospatialAPI.patch_feature_types - -Create features -^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.geospatial.GeospatialAPI.create_features - -Delete features -^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.geospatial.GeospatialAPI.delete_features - -Retrieve features -^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.geospatial.GeospatialAPI.retrieve_features - -Update features -^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.geospatial.GeospatialAPI.update_features - -List features -^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.geospatial.GeospatialAPI.list_features - -Search features -^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.geospatial.GeospatialAPI.search_features - -Stream features -^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.geospatial.GeospatialAPI.stream_features - -Aggregate features -^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.geospatial.GeospatialAPI.aggregate_features - -Get coordinate reference systems -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.geospatial.GeospatialAPI.get_coordinate_reference_systems - -List coordinate reference systems -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.geospatial.GeospatialAPI.list_coordinate_reference_systems - -Create coordinate reference systems -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.geospatial.GeospatialAPI.create_coordinate_reference_systems - - -Put raster data -^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.geospatial.GeospatialAPI.put_raster - -Delete raster data -^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.geospatial.GeospatialAPI.delete_raster - -Get raster data -^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.geospatial.GeospatialAPI.get_raster - -Compute -^^^^^^^ -.. automethod:: cognite.client._api.geospatial.GeospatialAPI.compute - -Geospatial Data classes -^^^^^^^^^^^^^^^^^^^^^^^ -.. automodule:: cognite.client.data_classes.geospatial - :members: - :show-inheritance: - - -Synthetic time series ---------------------- - -Calculate the result of a function on time series -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.synthetic_time_series.SyntheticDatapointsAPI.query - - -Time series ------------ - -.. warning:: - TimeSeries unit support is a new feature: - * The API specification is in beta. - * The SDK implementation is in alpha. - - Unit is implemented in the TimeSeries APIs with the parameters `unit_external_id` and `unit_quantity` in - the methods below. It is only the use of these arguments that is in alpha. Using the methods below - without these arguments is stable. - - Thus, breaking changes may occur without further notice, see :ref:`appendix-alpha-beta-features` for more information. - - -Retrieve a time series by id -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.time_series.TimeSeriesAPI.retrieve - -Retrieve multiple time series by id -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.time_series.TimeSeriesAPI.retrieve_multiple - -List time series -^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.time_series.TimeSeriesAPI.list - -Aggregate time series -^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.time_series.TimeSeriesAPI.aggregate - -Aggregate Time Series Count -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.time_series.TimeSeriesAPI.aggregate_count - -Aggregate Time Series Values Cardinality -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.time_series.TimeSeriesAPI.aggregate_cardinality_values - -Aggregate Time Series Property Cardinality -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.time_series.TimeSeriesAPI.aggregate_cardinality_properties - -Aggregate Time Series Unique Values -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.time_series.TimeSeriesAPI.aggregate_unique_values - -Aggregate Time Series Unique Properties -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.time_series.TimeSeriesAPI.aggregate_unique_properties - -Search for time series -^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.time_series.TimeSeriesAPI.search - -Create time series -^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.time_series.TimeSeriesAPI.create - -Delete time series -^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.time_series.TimeSeriesAPI.delete - -Filter time series -^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.time_series.TimeSeriesAPI.filter - -Update time series -^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.time_series.TimeSeriesAPI.update - -Upsert time series -^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.time_series.TimeSeriesAPI.upsert - - -Time Series Data classes -^^^^^^^^^^^^^^^^^^^^^^^^ -.. automodule:: cognite.client.data_classes.time_series - :members: - :show-inheritance: - - -Sequences ---------- - -Retrieve a sequence by id -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.sequences.SequencesAPI.retrieve - -Retrieve multiple sequences by id -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.sequences.SequencesAPI.retrieve_multiple - -List sequences -^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.sequences.SequencesAPI.list - -Aggregate sequences -^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.sequences.SequencesAPI.aggregate - -Aggregate Sequences Count -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.sequences.SequencesAPI.aggregate_count - -Aggregate Sequences Value Cardinality -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.sequences.SequencesAPI.aggregate_cardinality_values - -Aggregate Sequences Property Cardinality -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.sequences.SequencesAPI.aggregate_cardinality_properties - -Aggregate Sequences Unique Values -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.sequences.SequencesAPI.aggregate_unique_values - -Aggregate Sequences Unique Properties -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.sequences.SequencesAPI.aggregate_unique_properties - -Search for sequences -^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.sequences.SequencesAPI.search - -Create a sequence -^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.sequences.SequencesAPI.create - -Delete sequences -^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.sequences.SequencesAPI.delete - -Filter sequences -^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.sequences.SequencesAPI.filter - - -Update sequences -^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.sequences.SequencesAPI.update - -Upsert sequences -^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.sequences.SequencesAPI.upsert - - -Retrieve data -^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.sequences.SequencesDataAPI.retrieve - -Insert rows into a sequence -^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.sequences.SequencesDataAPI.insert - -Insert a pandas dataframe into a sequence -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.sequences.SequencesDataAPI.insert_dataframe - -Delete rows from a sequence -^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.sequences.SequencesDataAPI.delete - -Delete a range of rows from a sequence -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.sequences.SequencesDataAPI.delete_range - -Sequence Data classes -^^^^^^^^^^^^^^^^^^^^^ -.. automodule:: cognite.client.data_classes.sequences - :members: - :show-inheritance: - :exclude-members: Sequence - - .. autoclass:: Sequence - :noindex: - -Data Point Subscriptions ---------------------------- - -.. warning:: - DataPoint Subscription is a new feature: - * The API specification is in beta. - * The SDK implementation is in alpha. - - Thus, breaking changes may occur without further notice, see :ref:`appendix-alpha-beta-features` for more information. - - -Create data point subscriptions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.datapoints_subscriptions.DatapointsSubscriptionAPI.create - -Retrieve a data point subscription by id(s) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.datapoints_subscriptions.DatapointsSubscriptionAPI.retrieve - -List data point subscriptions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.datapoints_subscriptions.DatapointsSubscriptionAPI.list - -List member time series of subscription -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.datapoints_subscriptions.DatapointsSubscriptionAPI.list_member_time_series - -Iterate over subscriptions data -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.datapoints_subscriptions.DatapointsSubscriptionAPI.iterate_data - -Update data point subscription -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.datapoints_subscriptions.DatapointsSubscriptionAPI.update - -Delete data point subscription -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automethod:: cognite.client._api.datapoints_subscriptions.DatapointsSubscriptionAPI.delete - -Data Point Subscription classes -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automodule:: cognite.client.data_classes.datapoints_subscriptions - :members: - :show-inheritance: diff --git a/docs/source/data_modeling.rst b/docs/source/data_modeling.rst index d1d10d0eeb..296865bfbd 100644 --- a/docs/source/data_modeling.rst +++ b/docs/source/data_modeling.rst @@ -249,12 +249,6 @@ Instances query data classes :members: :show-inheritance: -Data Modeling Filtering data classes -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automodule:: cognite.client.data_classes.filters - :members: - :show-inheritance: - Data Modeling ID data classes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. automodule:: cognite.client.data_classes.data_modeling.ids diff --git a/docs/source/events.rst b/docs/source/events.rst new file mode 100644 index 0000000000..bb393fc558 --- /dev/null +++ b/docs/source/events.rst @@ -0,0 +1,67 @@ +Events +------ +Retrieve an event by id +^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.events.EventsAPI.retrieve + +Retrieve multiple events by id +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.events.EventsAPI.retrieve_multiple + +List events +^^^^^^^^^^^ +.. automethod:: cognite.client._api.events.EventsAPI.list + +Aggregate events +^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.events.EventsAPI.aggregate + +Aggregate Event Count +^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.events.EventsAPI.aggregate_count + +Aggregate Event Values Cardinality +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.events.EventsAPI.aggregate_cardinality_values + +Aggregate Event Property Cardinality +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.events.EventsAPI.aggregate_cardinality_properties + +Aggregate Event Unique Values +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.events.EventsAPI.aggregate_unique_values + +Aggregate Event Unique Properties +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.events.EventsAPI.aggregate_unique_properties + +Search for events +^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.events.EventsAPI.search + +Create events +^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.events.EventsAPI.create + +Delete events +^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.events.EventsAPI.delete + +Update events +^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.events.EventsAPI.update + +Upsert events +^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.events.EventsAPI.upsert + +Filter events +^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.events.EventsAPI.filter + +Events Data classes +^^^^^^^^^^^^^^^^^^^ +.. automodule:: cognite.client.data_classes.events + :members: + :show-inheritance: diff --git a/docs/source/files.rst b/docs/source/files.rst new file mode 100644 index 0000000000..a8835df307 --- /dev/null +++ b/docs/source/files.rst @@ -0,0 +1,63 @@ +Files +===== +Retrieve file metadata by id +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.files.FilesAPI.retrieve + +Retrieve multiple files' metadata by id +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.files.FilesAPI.retrieve_multiple + +List files metadata +^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.files.FilesAPI.list + +Aggregate files metadata +^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.files.FilesAPI.aggregate + +Search for files +^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.files.FilesAPI.search + +Create file metadata +^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.files.FilesAPI.create + +Upload a file or directory +^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.files.FilesAPI.upload + +Upload a string or bytes +^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.files.FilesAPI.upload_bytes + +Retrieve download urls +^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.files.FilesAPI.retrieve_download_urls + +Download files to disk +^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.files.FilesAPI.download + +Download a single file to a specific path +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.files.FilesAPI.download_to_path + +Download a file as bytes +^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.files.FilesAPI.download_bytes + +Delete files +^^^^^^^^^^^^ +.. automethod:: cognite.client._api.files.FilesAPI.delete + +Update files metadata +^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.files.FilesAPI.update + +Files Data classes +^^^^^^^^^^^^^^^^^^ +.. automodule:: cognite.client.data_classes.files + :members: + :show-inheritance: diff --git a/docs/source/filters.rst b/docs/source/filters.rst new file mode 100644 index 0000000000..3da9f1f329 --- /dev/null +++ b/docs/source/filters.rst @@ -0,0 +1,187 @@ +Filters +======= + +The filter language provides a set of classes that can be used to construct complex +queries for filtering data. Each filter class represents a specific filtering criterion, +allowing users to tailor their queries to their specific needs. Below is an overview of the +available filters: + +Filter +------ +Base class for all filters + +.. autoclass:: cognite.client.data_classes.filters.Filter + :members: + :member-order: bysource + +Logical Operators +----------------- + +And +^^^ +The `And` filter performs a logical AND operation on multiple filters, requiring all specified +conditions to be true for an item to match the filter. + +.. autoclass:: cognite.client.data_classes.filters.And + :members: + :member-order: bysource + +Not +^^^ +The `Not` filter performs a logical NOT operation on a sub-filter. + +.. autoclass:: cognite.client.data_classes.filters.Not + :members: + :member-order: bysource + +Or +^^^ +The `Or` filter performs a logical OR operation on multiple filters, requiring at least one +specified condition to be true for an item to match the filter. + +.. autoclass:: cognite.client.data_classes.filters.Or + :members: + :member-order: bysource + +Standard Filters +---------------- +Equals +^^^^^^ +The `Equals` filter checks if a property is equal to a specified value. + +.. autoclass:: cognite.client.data_classes.filters.Equals + :members: + :member-order: bysource + +Exists +^^^^^^ +The `Exists` filter checks if a property exists. + +.. autoclass:: cognite.client.data_classes.filters.Exists + :members: + :member-order: bysource + +ContainsAll +^^^^^^^^^^^ +The `ContainsAll` filter checks if an item contains all specified values for a given property. + +.. autoclass:: cognite.client.data_classes.filters.ContainsAll + :members: + :member-order: bysource + +ContainsAny +^^^^^^^^^^^ +The `ContainsAny` filter checks if an item contains any of the specified values for a given property. + +.. autoclass:: cognite.client.data_classes.filters.ContainsAny + :members: + :member-order: bysource + +In +^^ +The `In` filter checks if a property's value is in a specified list. + +.. autoclass:: cognite.client.data_classes.filters.In + :members: + :member-order: bysource + +Overlaps +^^^^^^^^ +The `Overlaps` filter checks if two ranges overlap. + +.. autoclass:: cognite.client.data_classes.filters.Overlaps + :members: + :member-order: bysource + +Prefix +^^^^^^ +The `Prefix` filter checks if a string property starts with a specified prefix. + +.. autoclass:: cognite.client.data_classes.filters.Prefix + :members: + :member-order: bysource + +Range +^^^^^ +The `Range` filter checks if a numeric property's value is within a specified range that can be +open-ended. + +.. autoclass:: cognite.client.data_classes.filters.Range + :members: + :member-order: bysource + +Search +^^^^^^ +The `Search` filter performs a full-text search on a specified property. + +.. autoclass:: cognite.client.data_classes.filters.Search + :members: + :member-order: bysource + +InAssetSubtree +^^^^^^^^^^^^^^ +The `InAssetSubtree` filter checks if an item belongs to a specified asset subtree. + +.. autoclass:: cognite.client.data_classes.filters.InAssetSubtree + :members: + :member-order: bysource + +Geo Filters +----------- +GeoJSON +^^^^^^^ +The `GeoJSON` filter performs geometric queries using GeoJSON representations. + +.. autoclass:: cognite.client.data_classes.filters.GeoJSON + :members: + :member-order: bysource + +GeoJSONDisjoint +^^^^^^^^^^^^^^^ +The `GeoJSONDisjoint` filter checks if two geometric shapes are disjoint. + +.. autoclass:: cognite.client.data_classes.filters.GeoJSONDisjoint + :members: + :member-order: bysource + +GeoJSONIntersects +^^^^^^^^^^^^^^^^^ +The `GeoJSONIntersects` filter checks if two geometric shapes intersect. + +.. autoclass:: cognite.client.data_classes.filters.GeoJSONIntersects + :members: + :member-order: bysource + +GeoJSONWithin +^^^^^^^^^^^^^ +The `GeoJSONWithin` filter checks if one geometric shape is within another. + +.. autoclass:: cognite.client.data_classes.filters.GeoJSONWithin + :members: + :member-order: bysource + +Data Modeling-Specific Filters +------------------------------ +HasData +^^^^^^^ +The `HasData` filter checks if an instance has data for a given property. + +.. autoclass:: cognite.client.data_classes.filters.HasData + :members: + :member-order: bysource + +MatchAll +^^^^^^^^ +The `MatchAll` filter matches all instances. + +.. autoclass:: cognite.client.data_classes.filters.MatchAll + :members: + :member-order: bysource + +Nested +^^^^^^ +The `Nested` filter applies a filter to the node pointed to by a direct relation property. + +.. autoclass:: cognite.client.data_classes.filters.Nested + :members: + :member-order: bysource diff --git a/docs/source/geospatial.rst b/docs/source/geospatial.rst new file mode 100644 index 0000000000..dcaee38ccb --- /dev/null +++ b/docs/source/geospatial.rst @@ -0,0 +1,99 @@ +Geospatial +========== +.. note:: + Check https://github.com/cognitedata/geospatial-examples for some complete examples. + +Feature types +------------- +Create feature types +^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.geospatial.GeospatialAPI.create_feature_types + +Delete feature types +^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.geospatial.GeospatialAPI.delete_feature_types + +List feature types +^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.geospatial.GeospatialAPI.list_feature_types + +Retrieve feature types +^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.geospatial.GeospatialAPI.retrieve_feature_types + +Update feature types +^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.geospatial.GeospatialAPI.patch_feature_types + +Features +-------- +Create features +^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.geospatial.GeospatialAPI.create_features + +Delete features +^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.geospatial.GeospatialAPI.delete_features + +Retrieve features +^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.geospatial.GeospatialAPI.retrieve_features + +Update features +^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.geospatial.GeospatialAPI.update_features + +List features +^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.geospatial.GeospatialAPI.list_features + +Search features +^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.geospatial.GeospatialAPI.search_features + +Stream features +^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.geospatial.GeospatialAPI.stream_features + +Aggregate features +^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.geospatial.GeospatialAPI.aggregate_features + +Reference systems +----------------- +Get coordinate reference systems +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.geospatial.GeospatialAPI.get_coordinate_reference_systems + +List coordinate reference systems +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.geospatial.GeospatialAPI.list_coordinate_reference_systems + +Create coordinate reference systems +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.geospatial.GeospatialAPI.create_coordinate_reference_systems + + +Raster data +----------- +Put raster data +^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.geospatial.GeospatialAPI.put_raster + +Delete raster data +^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.geospatial.GeospatialAPI.delete_raster + +Get raster data +^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.geospatial.GeospatialAPI.get_raster + +Compute +^^^^^^^ +.. automethod:: cognite.client._api.geospatial.GeospatialAPI.compute + +Geospatial Data classes +----------------------- +.. automodule:: cognite.client.data_classes.geospatial + :members: + :show-inheritance: \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index 6c57286b1b..2c6883410e 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -39,7 +39,13 @@ Contents cognite_client extensions_and_optional_dependencies identity_and_access_management - core_data_model + data_modeling + assets + events + files + time_series + sequences + geospatial 3d contextualization documents @@ -47,9 +53,9 @@ Contents data_organization transformations functions - data_modeling workflow_orchestration unit_catalog + filters deprecated base_data_classes exceptions diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst index 045b0ea791..d0d53c1ebb 100644 --- a/docs/source/quickstart.rst +++ b/docs/source/quickstart.rst @@ -65,8 +65,9 @@ You can also make your own credential provider: Discover time series -------------------- -For the next examples, you will need to supply ids for the time series that you want to retrieve. You can find some ids by listing the available time series. -Limits for listing resources default to 25, so the following code will return the first 25 time series resources. +For this, you will need to supply ids for the time series that you want to retrieve. You can find +some ids by listing the available time series. Limits for listing resources default to 25, so +the following code will return the first 25 time series resources. .. code:: python @@ -75,120 +76,13 @@ Limits for listing resources default to 25, so the following code will return th c = CogniteClient() ts_list = c.time_series.list() -Create an asset hierarchy -------------------------- -CDF organizes digital information about the physical world. Assets are digital representations of physical objects or -groups of objects, and assets are organized into an asset hierarchy. For example, an asset can represent a water pump -which is part of a subsystem on an oil platform. - -At the top of an asset hierarchy is a root asset (e.g., the oil platform). Each project can have multiple root assets. -Note that all assets must have a name (a non-empty string). - -To create a root asset (an asset without a parent), omit the parent ID when you post the asset to the API. -To make an asset a child of an existing asset, you must specify a parent ID (or parent external ID): - -.. code:: python - - from cognite.client import CogniteClient - from cognite.client.data_classes import Asset - - c = CogniteClient() - my_asset = Asset(name="my first child asset", parent_id=123) - c.assets.create(my_asset) - -To post an entire asset hierarchy, you can describe the relations within your asset hierarchy -using the ``external_id`` and ``parent_external_id`` attributes on the ``Asset`` object. You can post -an arbitrary number of assets, and the SDK will split the request into multiple requests. To make sure that the -assets are created in the correct order, you can use the ``create_hierarchy()`` function, which takes care of the -topological sorting for you, before splitting the request into smaller chunks. However, note that the ``create_hierarchy()`` -function requires the ``external_id`` property to be set for all assets. - -This example shows how to post a three levels deep asset hierarchy consisting of three assets. - -.. code:: python - - from cognite.client import CogniteClient - from cognite.client.data_classes import Asset - - c = CogniteClient() - root = Asset(name="root", external_id="1") - child = Asset(name="child", external_id="2", parent_external_id="1") - descendant = Asset(name="descendant", external_id="3", parent_external_id="2") - c.assets.create_hierarchy([root, child, descendant]) - -Wrap the ``create_hierarchy()`` call in a try-except to get information if creating the assets fails: - -- Which assets were created. (The request yielded a 201.) -- Which assets may have been created. (The request yielded 5xx.) -- Which assets were not created. (The request yielded 4xx, or was a descendant of another asset which may or may not have been created.) - -.. code:: python - - from cognite.client.exceptions import CogniteAPIError - try: - c.assets.create_hierarchy([root, child, descendant]) - except CogniteAPIError as err: - created = err.successful - maybe_created = err.unknown - not_created = err.failed - -Prior to creating the Assets, it might be useful to do some validation on the assets you have. To do this without -potentially sending API requests, import and use :class:`~cognite.client.data_classes.assets.AssetHierarchy`: - -.. code:: python - - from cognite.client.data_classes import AssetHierarchy - hierarchy = AssetHierarchy(assets) - # Get a report written to the terminal listing any issues: - hierarchy.validate_and_report() - # If there are issues, you may inspect them directly: - if not hierarchy.is_valid(): - hierarchy.orphans - hierarchy.invalid - hierarchy.unsure_parents - hierarchy.duplicates - hierarchy.cycles # Requires no other basic issues - -Note that validation will run automatically for you when calling ``create_hierarchy()``. You may choose to catch -``CogniteAssetHierarchyError`` and inspect any raised issues: - -.. code:: python - - from cognite.client.exceptions import CogniteAssetHierarchyError - try: - c.assets.create_hierarchy(assets) - except CogniteAssetHierarchyError as err: - # You may inspect the following attributes: - err.orphans - err.invalid - err.unsure_parents - err.duplicates - err.cycles # Requires no other basic issues - -Retrieve all events related to an asset subtree ------------------------------------------------ -Assets are used to connect related data together, even if the data comes from different sources; Time series of data -points, events and files are all connected to one or more assets. A pump asset can be connected to a time series -measuring pressure within the pump, as well as events recording maintenance operations, and a file with a 3D diagram -of the pump. - -To retrieve all events related to a given subtree of assets, we first fetch the subtree under a given asset using the -:code:`.subtree()` method. This returns an :code:`AssetList` object, which has a :code:`.events()` method. This method will -return events related to any asset in the :code:`AssetList`. +List available spaces in your Data Modeling project +--------------------------------------------------- +In the following example, we list all spaces in the project. .. code:: python from cognite.client import CogniteClient - from cognite.client.data_classes import Asset c = CogniteClient() - subtree_root_asset = "some-external-id" - subtree = c.assets.retrieve(external_id=subtree_root_asset).subtree() - related_events = subtree.events() - -You can use the same pattern to retrieve all time series or files related to a set of assets. - -.. code:: python - - related_files = subtree.files() - related_time_series = subtree.time_series() + spaces = c.data_modeling.spaces.list() \ No newline at end of file diff --git a/docs/source/sequences.rst b/docs/source/sequences.rst new file mode 100644 index 0000000000..9688d118be --- /dev/null +++ b/docs/source/sequences.rst @@ -0,0 +1,98 @@ +Sequences +========= + +Metadata +-------- +Retrieve a sequence by id +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.sequences.SequencesAPI.retrieve + +Retrieve multiple sequences by id +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.sequences.SequencesAPI.retrieve_multiple + +List sequences +^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.sequences.SequencesAPI.list + +Aggregate sequences +^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.sequences.SequencesAPI.aggregate + +Aggregate Sequences Count +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.sequences.SequencesAPI.aggregate_count + +Aggregate Sequences Value Cardinality +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.sequences.SequencesAPI.aggregate_cardinality_values + +Aggregate Sequences Property Cardinality +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.sequences.SequencesAPI.aggregate_cardinality_properties + +Aggregate Sequences Unique Values +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.sequences.SequencesAPI.aggregate_unique_values + +Aggregate Sequences Unique Properties +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.sequences.SequencesAPI.aggregate_unique_properties + +Search for sequences +^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.sequences.SequencesAPI.search + +Create a sequence +^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.sequences.SequencesAPI.create + +Delete sequences +^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.sequences.SequencesAPI.delete + +Filter sequences +^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.sequences.SequencesAPI.filter + + +Update sequences +^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.sequences.SequencesAPI.update + +Upsert sequences +^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.sequences.SequencesAPI.upsert + + +Rows +---- +Retrieve data +^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.sequences.SequencesDataAPI.retrieve + +Insert rows into a sequence +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.sequences.SequencesDataAPI.insert + +Insert a pandas dataframe into a sequence +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.sequences.SequencesDataAPI.insert_dataframe + +Delete rows from a sequence +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.sequences.SequencesDataAPI.delete + +Delete a range of rows from a sequence +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.sequences.SequencesDataAPI.delete_range + +Sequence Data classes +^^^^^^^^^^^^^^^^^^^^^ +.. automodule:: cognite.client.data_classes.sequences + :members: + :show-inheritance: + :exclude-members: Sequence + + .. autoclass:: Sequence + :noindex: \ No newline at end of file diff --git a/docs/source/time_series.rst b/docs/source/time_series.rst new file mode 100644 index 0000000000..6e60f2c1c6 --- /dev/null +++ b/docs/source/time_series.rst @@ -0,0 +1,197 @@ +Time Series +=========== + +Metadata +-------- + +.. warning:: + TimeSeries unit support is a new feature: + * The API specification is in beta. + * The SDK implementation is in alpha. + + Unit is implemented in the TimeSeries APIs with the parameters `unit_external_id` and `unit_quantity` in + the methods below. It is only the use of these arguments that is in alpha. Using the methods below + without these arguments is stable. + + Thus, breaking changes may occur without further notice, see :ref:`appendix-alpha-beta-features` for more information. + + +Retrieve a time series by id +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.time_series.TimeSeriesAPI.retrieve + +Retrieve multiple time series by id +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.time_series.TimeSeriesAPI.retrieve_multiple + +List time series +^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.time_series.TimeSeriesAPI.list + +Aggregate time series +^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.time_series.TimeSeriesAPI.aggregate + +Aggregate Time Series Count +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.time_series.TimeSeriesAPI.aggregate_count + +Aggregate Time Series Values Cardinality +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.time_series.TimeSeriesAPI.aggregate_cardinality_values + +Aggregate Time Series Property Cardinality +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.time_series.TimeSeriesAPI.aggregate_cardinality_properties + +Aggregate Time Series Unique Values +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.time_series.TimeSeriesAPI.aggregate_unique_values + +Aggregate Time Series Unique Properties +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.time_series.TimeSeriesAPI.aggregate_unique_properties + +Search for time series +^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.time_series.TimeSeriesAPI.search + +Create time series +^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.time_series.TimeSeriesAPI.create + +Delete time series +^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.time_series.TimeSeriesAPI.delete + +Filter time series +^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.time_series.TimeSeriesAPI.filter + +Update time series +^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.time_series.TimeSeriesAPI.update + +Upsert time series +^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.time_series.TimeSeriesAPI.upsert + +Time Series Data classes +^^^^^^^^^^^^^^^^^^^^^^^^ +.. automodule:: cognite.client.data_classes.time_series + :members: + :show-inheritance: + +Synthetic time series +--------------------- + +Calculate the result of a function on time series +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.synthetic_time_series.SyntheticDatapointsAPI.query + + + +Data points +----------- +.. warning:: + TimeSeries unit support is a new feature: + * The API specification is in beta. + * The SDK implementation is in alpha. + + Unit conversion is implemented in the Datapoints APIs with the parameters `target_unit` and `target_unit_system` in + the retrieve methods below. It is only the use of these arguments that is in alpha. Using the methods below + without these arguments is stable. + + Thus, breaking changes may occur without further notice, see :ref:`appendix-alpha-beta-features` for more information. + + +Retrieve datapoints +^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.datapoints.DatapointsAPI.retrieve + +Retrieve datapoints as numpy arrays +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.datapoints.DatapointsAPI.retrieve_arrays + +Retrieve datapoints in pandas dataframe +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.datapoints.DatapointsAPI.retrieve_dataframe + +Retrieve datapoints in time zone in pandas dataframe +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.datapoints.DatapointsAPI.retrieve_dataframe_in_tz + +Retrieve latest datapoint +^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.datapoints.DatapointsAPI.retrieve_latest + +Insert data points +^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.datapoints.DatapointsAPI.insert + +Insert data points into multiple time series +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.datapoints.DatapointsAPI.insert_multiple + +Insert pandas dataframe +^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.datapoints.DatapointsAPI.insert_dataframe + +Delete a range of data points +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.datapoints.DatapointsAPI.delete_range + +Delete ranges of data points +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.datapoints.DatapointsAPI.delete_ranges + + +Data Points Data classes +^^^^^^^^^^^^^^^^^^^^^^^^ +.. automodule:: cognite.client.data_classes.datapoints + :members: + :show-inheritance: + +Data Point Subscriptions +--------------------------- +.. warning:: + DataPoint Subscription is a new feature: + * The API specification is in beta. + * The SDK implementation is in alpha. + + Thus, breaking changes may occur without further notice, see :ref:`appendix-alpha-beta-features` for more information. + + +Create data point subscriptions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.datapoints_subscriptions.DatapointsSubscriptionAPI.create + +Retrieve a data point subscription by id(s) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.datapoints_subscriptions.DatapointsSubscriptionAPI.retrieve + +List data point subscriptions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.datapoints_subscriptions.DatapointsSubscriptionAPI.list + +List member time series of subscription +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.datapoints_subscriptions.DatapointsSubscriptionAPI.list_member_time_series + +Iterate over subscriptions data +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.datapoints_subscriptions.DatapointsSubscriptionAPI.iterate_data + +Update data point subscription +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.datapoints_subscriptions.DatapointsSubscriptionAPI.update + +Delete data point subscription +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automethod:: cognite.client._api.datapoints_subscriptions.DatapointsSubscriptionAPI.delete + +Data Point Subscription classes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. automodule:: cognite.client.data_classes.datapoints_subscriptions + :members: + :show-inheritance: \ No newline at end of file