Package: mixpanel-jql
A small Python library for runningJQLqueries against Mixpanel’s JQL API. The data returned from the API is
automatically decompressed as it arrives, making it available for
processing as soon as the first row arrives. This is to avoid buffering
large result sets in memory.InstallationTo install themixpanel-jqllibrary, simply run the following in
your terminal:pip installmixpanel-jqlSimple exampleLet’s do a simple count of our number of ‘X’ events over each day of May 2016. Our key for grouping will be the date the event was sent to Mixpanel in the formatYYYY-MM-DD. We can get that from our event’stimeproperty by specifying our key asnewDate(e.time).toISOString().split('T')[0].This is simple and fast to do with this library.fromdatetimeimportdatetimefrommixpanel_jqlimportJQL,Reducer,Eventsapi_secret='...'query=JQL(api_secret,events=Events({'event_selectors':[{'event':"X"}],'from_date':datetime(2016,5,1),'to_date':datetime(2016,5,31)})).group_by(keys=["new Date(e.time).toISOString().split('T')[0]",],accumulator=Reducer.count())forrowinquery.send():date=row['key'][0]value=row['value']print("[%s] =>%d"%(date,value))# [2016-05-01] => 302# [2016-05-02] => 1102# ...# [2016-05-31] => 120But what if we only want to count unique events? That is to say, what if we care about how many users spawned each event per day and not just the overall number of times the event occurred?With some minor modification to our previous code, we can achieve this:query=JQL(api_secret,events=Events({'event_selectors':[{'event':"X"}],'from_date':datetime(2016,5,1),'to_date':datetime(2016,5,31)})).group_by_user(keys=["new Date(e.time).toISOString().split('T')[0]",],accumulator="function(){ return 1;}").group_by(keys=["e.key.slice(1)"],accumulator=Reducer.count())We replace ouraccumulatorkeyward argument with a JavaScript function returning1, since each user will only be counted for once.group_by_useralso adds the user ID into the key of our results. We can regroup our results by slicing that detail off withe.key.slice(1)and recounting.More advanced examplesLet’s assume we want to count all events ‘A’ with a property ‘B’ that is
equal to 2 and a property F that is equal to “hello”. Events ‘A’ also
have a property ‘C’, which is some random string value. We want the
results grouped and tallied by values of ‘C’ to see how many property
‘C’ events occurred over each day in the month of April 2016.frommixpanel_jqlimportJQL,Reducer,Eventsapi_secret='...'query=JQL(api_secret,events=Events({'event_selectors':[{'event':"A"}],'from_date':'2016-04-01','to_date':'2016-04-30'})).filter('e.properties.B == 2').filter('e.properties.F == "hello"').group_by(keys=["new Date(e.time).toISOString().split('T')[0]","e.property.C"],accumulator=Reducer.count())forrowinquery.send():date,c=row['key']value=row['value']print("[%s]%s=>%d"%(date,c,value))# [2016-04-01] abc => 3# [2016-04-01] xyz => 1# ...If we wanted to count onlyuniqueevents (i.e. count each user causing
the event only once), we can change our query togroup by user, to
reduce the number of times they caused a particulare.properties.Cto just 1.query=JQL(api_secret,events=Events({'event_selectors':[{'event':"A"}],'from_date':'2016-04-01','to_date':'2016-04-30'})).filter('e.properties.B == 2').filter('e.properties.F == "hello"').group_by_user(keys=["new Date(e.time).toISOString().split('T')[0]","e.property.C"],accumulator="function(){ return 1;}").group_by(keys=["e.key.slice(1)"],accumulator=Reducer.count())Why are your filters not joined with&&?We could have also combined our.filter(...)methods into 1 method
by doing,.filter('e.properties.B== 2 && e.properties.F =="hello"').
Successive.filter(...)expressions are automatically&&’ed. The
method of expression you choose is stylistic.What is thatReducerthing?TheReducerclass is for convenience and contains shortcuts to all
the reducer functions (e.g.Reducer.count()returnsmixpanel.reducer.count(), andReducer.top(limit)returnsmixpanel.reducer.top(limit)). Refer to the code for a list of all
reducer shortcuts.To write your own reducer, make sure to include a full JavaScript
function body (i.e.function(){... }).What about conversions?TheConverterclass is another convenience for that.frommixpanel_jqlimportConverter...Converter.to_number('"xyz"')# Resolves to mixpanel.to_number("xyz")What about queries over “people” and “joins”?All of the previous examples are concerned primarily with JQL queries
over events. This library also supports queries over people and the join
of people and events. The following gives a skeleton for how that works.You are free to use only one ofeventsandpeople.join_paramsis only used if botheventsandpeopleare set.query=JQL(api_secret,events=Events({'event_selectors':[{'event':'...','selector':'...','label':'...'},...],'from_date':'<YYYY-MM-DD>','to_date':'<YYYY-MM-DD>'}),people=People({'user_selectors':[{'selector':'...'},...]}),join_params={'type':'full','selectors':[{'event':'...','selector':'...',},...]})....What other functions are supported?Mixpanel seems to be in a constant state of adding new functions beyond justfilterandmap.
The following are presently supported by this library. Refer to the code for their usage.filtermapflattensort_ascsort_descreducegroup_bygroup_by_userHow do I see what the final JavaScript sent to Mixpanel will be?Usestrmethod on your JQL query to view what the
equivalent JavaScript will be.>>>str(query)'function main() { return Events({"event_selectors": [{"event": "A"}], "from_date": "2016-04-01", "to_date": "2016-04-30"}).filter(function(e){return e.properties.B == 2}).filter(function(e){return e.properties.F == "hello"}).groupByUser([function(e){return new Date(e.time).toISOString().split(\'T\')[0]},function(e){return e.property.C}], function(){ return 1;}).groupBy([function(e){return e.key.slice(1)}], mixpanel.reducer.count()); }'This can be quite helpful during debugging.But what if you want something actually readable? That’s now possible too with the.prettymethod!>>>print(query.pretty)functionmain(){returnEvents({"event_selectors":[{"event":"A"}],"from_date":"2016-04-01","to_date":"2016-04-30"}).filter(function(e){returne.properties.B==2}).filter(function(e){returne.properties.F=="hello"}).groupByUser([function(e){returnnewDate(e.time).toISOString().split('T')[0]},function(e){returne.property.C}],function(){return1;}).groupBy([function(e){returne.key.slice(1)}],mixpanel.reducer.count());}Caveats.filter(...)automatically transforms whatever is within the
parenthesis’ intofunction(e){ return ... }.To override that behavior, and use things like theproperties.xshortcut syntax, use theraw(...)wrapper to insert whatever
JavaScript you want into thefilter,map.etc parameters.frommixpanel_jqlimportJQL,raw...query=JQL(api_secret,events=params).filter(raw(" function(e) {""   if (e.x > 3) {""     return true;""   } else {""     return false;""   }"" )")).filter('e.properties.F == "hello"')...This library cannot easily express everything possible in Mixpanel’s JQL
language, but does try to simplify the general cases. If you have some
ideas for making this library more user friendly to a wider range of
potential queries, please submit a pull request or create an issue.Contributions are very welcome!Where can I learn more about Mixpanel’s JQL?For more information on what you can do with JQL, refer to Mixpanel’s
documentationhere.