keen 0.4.0

Check Batch Upload Response For Errors

When you upload events in a batch, some of them may succeed and some of them may have errors. The Keen API returns information on each. Here’s an example:

Upload code (remember, Keen IO doesn’t allow periods in property names):

response = keen.add_events({
    "sign_ups": [
        { "username": "nameuser1" },
        { "username": "nameuser2", "an.invalid.property.name": 1 }
    ],
    "purchases": [
        { "price": 5 },
        { "price": 6 }
    ]
})

That code would result in the following API JSON response:

{
    "sign_ups": [
        {"success": true},
        {"success": false, "error": {"name": "some_error_name", "description": "some longer description"}}
    ],
    "purchases": [
        {"success": true},
        {"success": true}
    ]
}

So in python, to check on the results of your batch, you’d have code like so:

batch = {
    "sign_ups": [
        { "username": "nameuser1" },
        { "username": "nameuser2", "an.invalid.property.name": 1 }
    ],
    "purchases": [
        { "price": 5 },
        { "price": 6 }
    ]
}
response = keen.add_events(batch)

for collection in response:
    collection_result = response[collection]
    event_count = 0
    for individual_result in collection_result:
        if not individual_result["success"]:
            print("Event had error! Collection: '{}'. Event body: '{}'.".format(collection, batch[collection][event_count]))
        event_count += 1

Configure Unique Client Instances

If you intend to send events or query from different projects within the same python file, you’ll need to set up unique client instances (one per project). You can do this by assigning an instance of KeenClient to a variable like so:

from keen.client import KeenClient

client = KeenClient(
    project_id="xxxx",  # your project ID for collecting cycling data
    write_key="yyyy",
    read_key="zzzz",
    master_key="abcd" # not required for typical usage
)

client_hike = KeenClient(
    project_id="xxxx",  # your project ID for collecting hiking data (different from the one above)
    write_key="yyyy",
    read_key="zzzz",
    master_key="abcd" # not required for typical usage
)

You can send events like this:

# add an event to an event collection in your cycling project
client.add_event(...)

# or add an event to an event collection in your hiking project
client_hike.add_event(...)

Similarly, you can query events like this:

client.count(...)

Saved Queries

You can manage your saved queries from the Keen python client.

# Create your KeenClient
from keen.client import KeenClient

client = KeenClient(
    project_id="xxxx",  # your project ID
    read_key="zzzz",
    master_key="abcd" # Most Saved Query functionality requires master_key
)

# Create a saved query
saved_query_attributes = {
    # NOTE : For now, refresh_rate must explicitly be set to 0 unless you
    # intend to create a Cached Query.
    "refresh_rate": 0,
    "query": {
        "analysis_type": "count",
        "event_collection": "purchases",
        "timeframe": "this_2_weeks",
        "filters": [{
            "property_name": "price",
            "operator": "gte",
            "property_value": 1.00
        }]
    }
}

client.saved_queries.create("saved-query-name", saved_query_attributes)

# Get all saved queries
client.saved_queries.all()

# Get one saved query
client.saved_queries.get("saved-query-name")

# Get saved query with results
client.saved_queries.results("saved-query-name")

# NOTE : Updating Saved Queries requires sending the entire query definition. Any attribute not
# sent is interpreted as being cleared/removed. This means that properties set via another
# client, including the Projects Explorer Web UI, will be lost this way.
#
# The update() function makes this easier by allowing client code to just specify the
# properties that need updating. To do this, it will retrieve the existing query definition
# first, which means there will be two HTTP requests. Use update_full() in code that already
# has a full query definition that can reasonably be expected to be current.

# Update a saved query to now be a cached query with the minimum refresh rate of 4 hrs...

# ...using partial update:
client.saved_queries.update("saved-query-name", { "refresh_rate": 14400 })

# ...using full update, if we've already fetched the query definition:
saved_query_attributes["refresh_rate"] = 14400
client.saved_queries.update_full("saved-query-name", saved_query_attributes)

# Update a saved query to a new resource name...

# ...using partial update:
client.saved_queries.update("saved-query-name", { "query_name": "cached-query-name" })

# ...using full update, if we've already fetched the query definition or have it lying around
# for whatever reason. We send "refresh_rate" again, along with the entire definition, or else
# it would be reset:
saved_query_attributes["query_name"] = "cached-query-name"
client.saved_queries.update_full("saved-query-name", saved_query_attributes)

# Delete a saved query (use the new resource name since we just changed it)
client.saved_queries.delete("cached-query-name")

Overwriting event timestamps

Two time-related properties are included in your event automatically. The properties “keen.timestamp” and “keen.created_at” are set at the time your event is recorded. You have the ability to overwrite the keen.timestamp property. This could be useful, for example, if you are backfilling historical data. Be sure to use ISO-8601 Format.

Keen stores all date and time information in UTC!

keen.add_event("sign_ups", {
    "keen": {
        "timestamp": "2012-07-06T02:09:10.141Z"
    },
    "username": "lloyd",
    "referred_by": "harry"
})

Get from Keen IO with a Timeout

By default, GET requests will timeout after 305 seconds. If you want to manually override this, you can create a KeenClient with the “get_timeout” parameter. This client will fail GETs if no bytes have been returned by the server in the specified time. For example:

from keen.client import KeenClient

client = KeenClient(
    project_id="xxxx",
    write_key="yyyy",
    read_key="zzzz",
    get_timeout=100
)

This will cause queries such as count(), sum(), and average() to timeout after 100 seconds. If this timeout limit is hit, a requests.Timeout will be raised. Due to a bug in the requests library, you might also see an SSLError (#1294)

Send to Keen IO with a Timeout

By default, POST requests will timeout after 305 seconds. If you want to manually override this, you can create a KeenClient with the “post_timeout” parameter. This client will fail POSTs if no bytes have been returned by the server in the specified time. For example:

from keen.client import KeenClient

client = KeenClient(
    project_id="xxxx",
    write_key="yyyy",
    post_timeout=100
)

This will cause both add_event() and add_events() to timeout after 100 seconds. If this timeout limit is hit, a requests.Timeout will be raised. Due to a bug in the requests library, you might also see an SSLError (https://github.com/kennethreitz/requests/issues/1294)

Create Scoped Keys

The Python client enables you to create Scoped Keys easily. For example:

from keen.client import KeenClient
from keen import scoped_keys

api_key = KEEN_MASTER_KEY

write_key = scoped_keys.encrypt(api_key, {"allowed_operations": ["write"]})
read_key = scoped_keys.encrypt(api_key, {"allowed_operations": ["read"]})

write_key and read_key now contain scoped keys based on your master API key.