Applying Tags

Tagging allows you to add your own metadata to interactions before they reach your application.

To add tags to any CSDL filter, first wrap the filtering code in a return statement. Then add the tagging code. This has to appear before the return otherwise the filter will not compile.

For example:

// Here's the tagging logic
tag "iPhone" { bitly.user.agent substr "iPhone"
               OR interaction.source contains "iPhone" }
tag "Blackberry" { bitly.user.agent substr "Blackberry"
                   OR interaction.source contains "Blackberry" }
tag "iOS" { bitly.user.agent substr "iPhone" 
            OR bitly.user.agent substr "iPad"
            OR interaction.source contains_any "iPhone,iPad" }

// Here's the filtering logic
return {
    interaction.content contains "Venice" OR links.title contains "Venice"
}

Defining tags

You can apply any tag to an interaction just once. For example, this code is fine:

tag "iPhone" { interaction.source substr "iPhone" }
tag "Blackberry" { interaction.source contains "Blackberry"}

But this code will not compile because it attempts to assign a value to the same tag twice:

tag "iPhone" { interaction.source substr "iPhone" }
// tag "iPhone" { bitly.user.agent substr "iPhone" }

// We've commented the second tag definition because 
// you can't define a tag twice

Instead, the compiler will insist on code such as this, which assigns the tag value only once:

tag "iPhone" { bitly.user.agent substr "iPhone"
               OR interaction.source contains "iPhone" }

Valid characters

The tags can be any string values you choose formed from the following valid characters:

  • latin letters excluding accents
  • digits
  • hyphens
  • spaces
  • underscores

For example the following tags are all valid:

tag "café" { fb.all.content any "café" } 
tag "Peets Coffee" { fb.all.content any "Peets, Peet's" } 
tag "501" { fb.all.content any "Levis 501" }

Understanding the output

For the simple tagging described on this page, if the input contains these two interactions:

{
    "interaction": {
        "content": "Check out my holiday pics, Venice was beautiful!",
        "source": "Twitter for iPhone"
    },
    “twitter”: {
        …
    }
}

{
    "interaction": {
        "link": "http://www.italia.it/en/discover-italy/veneto/venice.html"
    },
    "bitly": {
        "user": {
            "agent": "BlackBerry9700/5.0.0.862 Profile/MIDP-2.1 Configuration/CLDC-1.1 VendorID/144"
        }
    }
}

The output looks like this. Notice that the tags appear as an array of strings beneath interaction.tags:

{
    "interaction": {
        "content": "Check out my holiday pics, Venice was beautiful!",
        "source": "Twitter for iPhone",
        "tags": [
            "iPhone",
            "iOS"
        ]
    }
}

{
    "interaction": {
        "link": "http://www.italia.it/en/discover-italy/veneto/venice.html",
        "tags": [
            "Blackberry"
        ]
    },
    "bitly": {
        "user": {
            "agent": "BlackBerry9700/5.0.0.862 Profile/MIDP-2.1 Configuration/CLDC-1.1 VendorID/144"
        }
    }
}

For reasons of brevity, these JSON objects are shown here as fragments with only the relevant elements visible.

How many tags can I use?

You can currently use up to 10,000 tags in each of your filters. It does not matter whether you define them locally or include them from external definitions. We may adjust the limit from time to time, either up or down, depending on the load on DataSift's platform.