Expression Editor: Query Language

[Maihem]

Expression Editor: Query Language

Table of contents

1. Introduction
2. Auracen's XE guide
3. Formal grammar
4. List of identifiers and constants

Notes

[29-Jun-2011 22:40] Fixed targetMobId description.

[10-Mar-2011 14:26] Added extraSpellId/extraSpell fields and new POWER_ constants.

[26-May-2010 15:08] Added ACTOR RAID ICONS constants. Will be live sometime next week. Until then, use the numeric values provided.

[21-May-2010 21:30] Finally included Auracen's XE guide.

[21-Mar-2010 00:49] Formal grammar optimized for 68-column layout ([code] in polyethylene).

[Maihem]

1. Introduction

The single most detailed and customizable way to inspect a WoL report is using the Expression Editor (a.k.a. XE). The XE, like the Log Browser that was deprecated in favor of it, allows you to inspect every single event in the log. What's more, you can input a filter expression to show only events of interest. The language this expression is written in is based on SQL, which makes it very extensible and rather easy to read and create.

This topic will describe this expression (or query) language in its current state. Included are a full formal grammar and a list of identifiers and constants along with their descriptions. Significant changes made to the QL will also be posted and detailed here.

[Maihem]

2. Auracen's XE guide

Auracen wrote up an awesome guide to the XE at PlusHeal.com and has graciously allowed me to repost it here for your perusal. The original may be found at the PlusHeal.com forums as this version may lag behind a little on updates.

/bow Auracen.


World of Logs - Expression Editor

I discovered a fun little tool in World of logs recently, the Expression Editor. It can go beyond what you normally can see from World of Logs standard dps/hps reports. It is very powerful, but has taken me a bit to start understanding the syntax and building useful queries. I thought I'd write up some documentation on how to use it since I haven't found much yet.

This guide is a work in progress, and constructive feedback is always welcomed. If there is anything I have missed or any pieces that are hard to understand, feel free to ask questions and I can add to or explain complicated pieces.

Getting Started

Go to the fight or raid you want to analyze, and then under the drop down menu where you would normally choose Damage Done, or Healing done, etc, choose Expression Editor. If you choose one specific fight, your query will likely return faster since it has less of the combat log to look through than just choosing the entire raid. This will also eliminate any unwanted data such as when you are just clearing trash mobs.



Once at the Expression Editor screen, you will be given a query text box. You will enter an expression in the query you want, and hit run. World of Logs will return any line of the combat log that qualifies on your query.

I'll start with an example... I play a restoration druid and let's say I want to know how often I cast rejuvenation on a target that is already effected by rejuvenation (This can be thought of as refreshing a DoT before the last tick... a loss of HPS/DPS). This is actually pretty easy to do with the expression editor, but would be virtually impossible to find out through looking elsewhere on worldoflogs. So, to implement this example I would enter the following into the expression editor:

Code: Select all

sourceName = "Auracen" and fullType = SPELL_AURA_REFRESH and healSpell = "Rejuvenation"

What this is telling the editor is give me any event where the source of the spell/ability is Auracen, the type of action is SPELL_AURA_REFRESH, and the spell cast is Rejuvenation. Running this gives me a little report, like this:



The and/or logic can be kind of confusing if you haven't done much programming... I And everything together, so that all of those qualities are required. If you want one condition or another, you use the word or. So lets say I want to see refreshes on Rejuvenation Or Regrowth. I still only want to see spells cast by "Auracen" and I still want to only see spells cast with a fullType of SPELL_AURA_REFRESH so when dealing with those clauses I need to use the and operator. However no line will qualify if I say I want lines where the spell is Rejuvenation and Regrowth, so I need to use the or qualifier there. It will look something like this:

Code: Select all

sourceName = "Auracen"
and fullType = SPELL_AURA_REFRESH
and (healSpell = "Rejuvenation" or healSpell = "Regrowth)

Notice that I have to use the ( )'s around Rejuvenation or Regrowth so that the query knows the order of operations. Without the parenthesis it would return (All spells cast by Auracen, that refreshed an aura, and was rejuvenation) or any spellcast of Regrowth. Which is not what we are looking for.

Building more complex queries

Another example... something slightly more complex. Let's build a report that will essentially show us who has been messing up on the Sindragosa encounter. We will qualify on any line in the log file where someone got more than 5 stacks of Mystic Buffet, and 6 stacks of Instability or Chilled to the bone. But on Unchained Magic only, lets ignore the mages and Shadow priests (In my guild Kouji, Trippz, and Heartfrost) since they can Ice Block or Dispersion it. We are also only concerned about players... not pets, so adding the and targetType = "Player" will make our query slightly cleaner.

Code: Select all

(
     (spell = "Mystic Buffet" and amount > 5) or
     (
     (spell = "Instability" or spell = "Chilled to the Bone")
     and amount >  6 and fullType = SPELL_AURA_APPLIED_DOSE
     and (targetName != "kouji" and targetName != "trippz" and targetName != "heartfrost")
     )
)
and targetType = "Player"


This is going to return something like:



There is a formal grammar defined for the language, as well as identifiers and constants that you can use when building expressions. Constants would be things like spell, amount, targetName. They can all be found here.

In order to build your queries, looking through the constants will be required as any query will hinge upon what is available by the editor. Not everything is possible to find using the expression editor, basic rule would be if you cannot manually search the combat logs to find what you are looking for, the expression editor will not do it either. The editor is basically a way to simplify searching thousands of lines in the log file for the one piece you are interested in.

A final tip is if you are having trouble getting a large expression to work, break it up into smaller chunks... once you get the chunks working, piece it back together.

[Maihem]

3. Formal grammar

To facilitate those wanting to get the most out of the language, I here present a formal grammar. This grammar uses ABNF to express the anatomy of the QL in its current state.

Code: Select all

expression              =   orExpression

orExpression            =   andExpression
                            *( "or" andExpression )

andExpression           =   equalityExpression
                            *( "and" equalityExpression )

equalityExpression      =   relationalExpression
                            [   ( "=" / "!=" )
                                relationalExpression
                            ]

relationalExpression    =   identExpression [ "not" ] "in" list
                        /   additiveExpression
                            [   ( "<" / "<=" / ">=" / ">" )
                                additiveExpression
                            ]

additiveExpression      =   multiplicativeExpression
                            *(  ( "+" / "-" )
                                multiplicativeExpression
                            )

multiplicativeExpression =  unaryExpression
                            *(  (   "*"
                                /   "/" ; not currently supported
                                /   "%" ; not currently supported
                                )
                                unaryExpression
                            )

unaryExpression         =   *( "not" / "+" / "-" ) primaryExpression

primaryExpression       =   "(" expression ")"
                        /   identExpression
                        /   literal

identExpression         =   IDENTIFIER

literal                 =   CONSTANT
                        /   STRING
                        /   NUMBER
                        /   "true"
                        /   "false"

list                    =   "(" literal *( "," literal ) ")"

IDENTIFIER              =   ( ALPHA / "_" ) *( ALPHA / DIGIT / "_" )

CONSTANT                =   UC_ALPHA 1*( UC_ALPHA / "_" )

STRING                  =   "'" *( SQ_ESC_CHR / SQ_STR_CHR ) "'"
                        \   DQUOT *( DQ_ESC_CHR / DQ_STR_CHR ) DQUOT

NUMBER                  =   1*DIGIT

UC_ALPHA                =   %x41-5A     ; 'A'..'Z'

SQ_ESC_CHR              =   "\" ( "'" / "\" )

SQ_STR_CHR              =   %x00-26 / %x28-5B / %x5D-FF
                            ; all but "'" and "\"

DQUOT                   =   DQUOTE

DQ_ESC_CHR              =   "\" ( DQUOT / "\" )

DQ_STR_CHR              =   %x00-21 / %x23-5B / %x5D-FF
                            ; all but DQUOT and "\"

[Maihem]

4. List of identifiers and constants

Up next is a list of all identifiers in the language and a description of their values.

Code: Select all

###################
##  Identifiers  ##
###################


Event
    type                = Number: Event type (see EVENT TYPES)
    subType             = Number: Event subtype (undocumented, use fullType)
    fullType            = Number: Event type and subtype combined (see FULL EVENT TYPES)
   
    missType            = Number: Event (TYPE_MISS) miss type (see MISS TYPES)
    powerType           = Number: Event (ENERGIZE/DRAIN/LEECH) power type (see POWER TYPES)
   
    isCritical          = Boolean: Event is critical
    isCrushing          = Boolean: Event is crushing
    isGlancing          = Boolean: Event is glancing
   
    spellId             = Number: Spell ID
    spell               = String: Spell name
    school              = Number: Spell school (see SPELL SCHOOLS)
   
    extraSpellId      = Number: Extra spell ID
    extraSpell         = String: Extra spell name
   
    NOTE: Extra spell fields are present for events that refer to more than one spell,
          like SPELL_INTERRUPT, _DISPEL, _DISPEL_FAILED, _STOLEN and _AURA_BROKEN_SPELL.

    amount              = Number: Event amount
    absorbed            = Number: Event amount absorbed
    blocked             = Number: Event amount blocked
    resisted            = Number: Event amount resisted
    missAmount          = Number: Event amount missed
    overheal            = Number: Event amount overhealed
    overkill            = Number: Event amount overkill
   
    healingDone         = Number: WOL healing done amount (amount - overheal + absorbed)
    damageTaken         = Number: WOL damage taken amount
                                (missAmount if type = TYPE_MISS and missType = MISS_ABSORB
                                        else amount + absorbed)
                               
                                NOTE: Identifier missType is not in query language.


Event source/target actors
    sourceId            = Number: WOL source actor ID
    sourceUid           = Number: WOL merged source actor ID
    masterSourceUid     = Number: WOL merged actor ID of source's master
    sourceMobId         = Number: Source actor mob ID
    sourceName          = String: Source actor name
    sourceType          = String: Source actor type (see ACTOR TYPES)
    sourceReaction      = Number: Source actor reaction (see ACTOR REACTIONS)
    sourceAffiliation   = Number: Source actor affiliation (see ACTOR AFFILIATIONS)
    sourceInRaid      = Boolean: Source actor is in raid
    sourceIcon          = Number: Source actor raid icon (see ACTOR RAID ICONS)

    targetId            = Number: WOL target actor ID
    targetUid           = Number: WOL merged target actor ID
    targetMobId         = Number: Target actor mob ID
    targetName          = String: Target actor name
    targetType          = String: Target actor type
    targetReaction      = Number: Target actor reaction (see ACTOR REACTIONS)
    targetAffiliation   = Number: Target actor affiliation (see ACTOR AFFILIATIONS)
    targetInRaid      = Boolean: Target actor is in raid
    targetIcon          = Number: Target actor raid icon (see ACTOR RAID ICONS)


Healing event
    healSourceId        = Number: WOL source actor ID (with shield support)
    healSourceUid       = Number: WOL merged source actor ID (with shield support)
    masterHealSourceUid = Number: WOL merged actor ID of source's master (with shield support)

    healSpellId         = Number: Spell ID (with shield support)
    healSpell           = String: Spell name (with shield support)




#################
##  Constants  ##
#################


EVENT TYPES
    TYPE_DAMAGE                 = 1
    TYPE_MISS                   = 2
    TYPE_HEAL                   = 3
    TYPE_AURA                   = 4
    TYPE_DEATH                  = 5
    TYPE_CAST                   = 6
    TYPE_DISPEL                 = 7
    TYPE_GAIN                   = 8
    TYPE_ENCHANT                = 9
    TYPE_DURABILITY             = 10
    TYPE_SUMMON                 = 11
    TYPE_OTHER                  = 50


FULL EVENT TYPES
    SWING_DAMAGE                = 101
    RANGE_DAMAGE                = 102
    SPELL_DAMAGE                = 103
    SPELL_PERIODIC_DAMAGE       = 104
    DAMAGE_SPLIT                = 105
    DAMAGE_SHIELD               = 106
    ENVIRONMENTAL_DAMAGE        = 107
    SPELL_BUILDING_DAMAGE       = 108
   
    SWING_MISSED                = 201
    RANGE_MISSED                = 202
    SPELL_MISSED                = 203
    SPELL_PERIODIC_MISSED       = 204
    DAMAGE_SHIELD_MISSED        = 205
   
    SPELL_HEAL                  = 301
    SPELL_PERIODIC_HEAL         = 302
    SPELL_BUILDING_HEAL         = 303
   
    SPELL_AURA_APPLIED          = 401
    SPELL_AURA_APPLIED_DOSE     = 402
    SPELL_AURA_REMOVED          = 403
    SPELL_AURA_REMOVED_DOSE     = 404
    SPELL_EXTRA_ATTACKS         = 405
    SPELL_AURA_REFRESH          = 406
   
    PARTY_KILL                  = 501
    UNIT_DIED                   = 502
    UNIT_DESTROYED              = 503
    SPELL_INSTAKILL             = 504
   
    SPELL_CAST_START            = 601
    SPELL_CAST_SUCCESS          = 602
    SPELL_CAST_FAILED           = 603
   
    SPELL_INTERRUPT             = 701
    SPELL_DISPEL                = 702
    SPELL_DISPEL_FAILED         = 703
    SPELL_STOLEN                = 704
    SPELL_AURA_BROKEN           = 705
    SPELL_AURA_BROKEN_SPELL     = 706
   
    SPELL_ENERGIZE              = 801
    SPELL_DRAIN                 = 802
    SPELL_LEECH                 = 803
    SPELL_PERIODIC_ENERGIZE     = 804
    SPELL_PERIODIC_DRAIN        = 805
    SPELL_PERIODIC_LEECH        = 806
   
    ENCHANT_APPLIED             = 901
    ENCHANT_REMOVED             = 902
   
    SPELL_DURABILITY_DAMAGE     = 1001
    SPELL_DURABILITY_DAMAGE_ALL = 1002
   
    SPELL_SUMMON                = 1101
   
    SPELL_CREATE                = 5001
    SPELL_RESURRECT             = 5002


MISS TYPES
    MISS_ABSORB                 = 1
    MISS_BLOCK                  = 2
    MISS_DEFLECT                = 3
    MISS_DODGE                  = 4
    MISS_EVADE                  = 5
    MISS_IMMUNE                 = 6
    MISS_MISS                   = 7
    MISS_PARRY                  = 8
    MISS_RESIST                 = 9
    MISS_REFLECT                = 10
    MISS_MISFIRE                = 11


POWER TYPES
    POWER_HEALTH                = -2
    POWER_MANA                  = 0
    POWER_RAGE                  = 1
    POWER_FOCUS                 = 2
    POWER_ENERGY                = 3
    POWER_HAPPINESS             = 4
    POWER_RUNES                 = 5
    POWER_RUNIC_POWER           = 6
    POWER_SOUL_SHARDS           = 7
    POWER_ECLIPSE               = 8
    POWER_POWER_ECLIPSE         = 8  (alias for POWER_ECLIPSE)
    POWER_HOLY_POWER            = 9
    POWER_ALTERNATE_POWER       = 10
    POWER_DARK_FORCE            = 11
    POWER_LIGHT_FORCE           = 12
    POWER_SHADOW_ORBS           = 13
    POWER_BURNING_EMBERS        = 14
   


SPELL SCHOOLS
    PHYSICAL                    = 1
    HOLY                        = 2
    FIRE                        = 4
    NATURE                      = 8
    FROST                       = 16
    SHADOW                      = 32
    ARCANE                      = 64
   
    NOTE: Spell schools are bitwise cumulative for multi-school spells.


ACTOR TYPES
    "Player"
    "Creature"
    "Pet"
    "Vehicle"
    "Unknown"


ACTOR REACTIONS
    REACTION_FRIENDLY           = 16
    REACTION_NEUTRAL            = 32
    REACTION_HOSTILE            = 64


ACTOR AFFILIATIONS
   AFFILIATION_MINE         = 1;
   AFFILIATION_PARTY         = 2;
   AFFILIATION_RAID         = 4;
   AFFILIATION_OUTSIDER      = 8;


ACTOR RAID ICONS
    ICON_STAR                   = 1
    ICON_CIRCLE                 = 2
    ICON_DIAMOND                = 4
    ICON_TRIANGLE               = 8
    ICON_MOON                   = 16
    ICON_SQUARE                 = 32
    ICON_CROSS                  = 64
    ICON_SKULL                  = 128