Merge pull request #150 from SteadBytes/cached-datasets

Cached Datasets Support

Author: masojus

README.rst

@@ -406,6 +406,85 @@ You can manage your `saved queries <https://keen.io/docs/api/?shell#saved-querie
     # Delete a saved query (use the new resource name since we just changed it)
     client.saved_queries.delete("cached-query-name")
 
+Cached Datasets
+'''''''''''''''
+.. code-block:: python
+
+    # Create your KeenClient
+    from keen.client import KeenClient
+
+    client = KeenClient(
+        project_id="xxxx",  # your project ID
+        read_key="zzzz",
+        master_key="abcd" 
+    )
+
+    # Create a Cached Dataset
+    dataset_name = "NEW_DATASET"
+    display_name = "My new dataset"
+    query = {
+        "project_id": "PROJECT ID",
+        "analysis_type": "count",
+        "event_collection": "purchases",
+        "filters": [
+            {
+                "property_name": "price",
+                "operator": "gte",
+                "property_value": 100
+            }
+        ],
+        "timeframe": "this_500_days",
+        "timezone": None,
+        "interval": "daily",
+        "group_by": ["ip_geo_info.country"]
+    }
+    index_by = "product.id"
+    client.cached_datasets.create(
+        dataset_name,
+        query,
+        index_by,
+        display_name
+    )
+
+    # Get all Cached Datasets
+    client.cached_datasets.all()
+
+    # Get one Cached Dataset
+    client.cached_datasets.get(dataset_name)
+
+    # Retrieve Cached Dataset results
+    index_by = "a_project_id"
+    timeframe ="this_2_hours"
+    client.cached_datasets.results(
+        dataset_name,
+        index_by,
+        timeframe
+    )
+
+    # Using an absolute timeframe
+    timeframe = {
+        "start": "2018-11-02T00:00:00.000Z",
+        "end": "2018-11-02T02:00:00.000Z"
+    }
+    client.cached_datasets.results(
+        dataset_name,
+        index_by,
+        timeframe
+    )
+
+    # Using multiple index_by values
+    index_by = {
+        "project.id": "a_project_id",
+        "project.foo": "bar"
+    }
+    client.cached_datasets.results(
+        "dataset_with_multiple_indexes",
+        index_by,
+        timeframe
+    )
+
+    # Delete a Cached Dataset
+    client.cached_datasets.delete(dataset_name)
 
 Overwriting event timestamps
 ''''''''''''''''''''''''''''

keen/cached_datasets.py

@@ -0,0 +1,91 @@
+import json
+
+from keen.api import HTTPMethods
+from keen.utilities import KeenKeys, headers, requires_key
+
+
+class CachedDatasetsInterface:
+
+    def __init__(self, api):
+        self.api = api
+        self._cached_datasets_url = "{0}/{1}/projects/{2}/datasets".format(
+            self.api.base_url, self.api.api_version, self.api.project_id
+        )
+
+    @requires_key(KeenKeys.READ)
+    def all(self):
+        """ Fetch all Cached Datasets for a Project. Read key must be set.
+        """
+        return self._get_json(HTTPMethods.GET,
+                              self._cached_datasets_url,
+                              self._get_master_key())
+
+    @requires_key(KeenKeys.READ)
+    def get(self, dataset_name):
+        """ Fetch a single Cached Dataset for a Project. Read key must be set.
+
+        :param dataset_name: Name of Cached Dataset (not `display_name`)
+        """
+        url = "{0}/{1}".format(self._cached_datasets_url, dataset_name)
+        return self._get_json(HTTPMethods.GET, url, self._get_read_key())
+
+    @requires_key(KeenKeys.MASTER)
+    def create(self, dataset_name, query, index_by, display_name):
+        """ Create a Cached Dataset for a Project. Master key must be set.
+        """
+        url = "{0}/{1}".format(self._cached_datasets_url, dataset_name)
+        payload = {
+            "query": query,
+            "index_by": index_by,
+            "display_name": display_name
+        }
+        return self._get_json(HTTPMethods.PUT, url, self._get_master_key(), json=payload)
+
+    @requires_key(KeenKeys.READ)
+    def results(self, dataset_name, index_by, timeframe):
+        """ Retrieve results from a Cached Dataset. Read key must be set.
+        """
+        url = "{0}/{1}/results".format(self._cached_datasets_url, dataset_name)
+
+        index_by = index_by if isinstance(index_by, str) else json.dumps(index_by)
+        timeframe = timeframe if isinstance(timeframe, str) else json.dumps(timeframe)
+
+        query_params = {
+            "index_by": index_by,
+            "timeframe": timeframe
+        }
+
+        return self._get_json(
+            HTTPMethods.GET, url, self._get_read_key(), params=query_params
+        )
+
+    @requires_key(KeenKeys.MASTER)
+    def delete(self, dataset_name):
+        """ Delete a Cached Dataset. Master Key must be set.
+        """
+        url = "{0}/{1}".format(self._cached_datasets_url, dataset_name)
+        self._get_json(HTTPMethods.DELETE, url, self._get_master_key())
+        return True
+
+    def _get_json(self, http_method, url, key, *args, **kwargs):
+        response = self.api.fulfill(
+            http_method,
+            url,
+            headers=headers(key),
+            *args,
+            **kwargs)
+
+        self.api._error_handling(response)
+
+        try:
+            response = response.json()
+        except ValueError:
+            response = "No JSON available."
+
+        return response
+
+    def _get_read_key(self):
+        return self.api._get_read_key()
+
+    def _get_master_key(self):
+        return self.api._get_master_key()

keen/client.py

@@ -2,7 +2,7 @@
 import copy
 import json
 import sys
-from keen import persistence_strategies, exceptions, saved_queries
+from keen import persistence_strategies, exceptions, saved_queries, cached_datasets
 from keen.api import KeenApi
 from keen.persistence_strategies import BasePersistenceStrategy
 
@@ -98,6 +98,7 @@ def __init__(self, project_id, write_key=None, read_key=None,
         self.get_timeout = get_timeout
         self.post_timeout = post_timeout
         self.saved_queries = saved_queries.SavedQueriesInterface(self.api)
+        self.cached_datasets = cached_datasets.CachedDatasetsInterface(self.api)
 
     if sys.version_info[0] < 3:
         @staticmethod