document-filters.md

Mapping JSON documents to POCOs with DocumentFilters

Couchbase allows you store heterogeneous documents within a Bucket or "keyspace". When you do a select without a predicate, you are querying across the entire keyspace. For example, imagine a bucket with various document "types" and you do a N1QL query like this:

SELECT name FROM `travel-sample`;

This query will return the name field for every document in the keystore. It's more likely you would want to constrain the query to a subset of the entire keystore, returning results from only one kind of document, so you would do something like this:

SELECT name FROM `travel-sample` WHERE type="airline";

In your application, this would translate to a Linq query that maps the document to an C# object with strongly typed fields matching the document:

var query = from x in db.Query<Airline>()
	where x.Type == "airline"
	select x.Name;	

Now, this is nice and all but becomes a but tedious to do for every query. Instead what you want to do is remove the explicit Type predicate from the query:

var query = from x in db.Query<Airline>()
	select x.Name;	

This is exactly what Document Filters allow you to do: map a JSON document to a C# POCO without explicitly (and redundantly) having to provide a predicate (WHERE) based on the "type" field. Instead you create either create a custom DocumentFilter or you use a DocumentTypeFilterAttribute and you associate it with your C# class or POCO.

##Using the DocumentTypeFilterAttribute## Assuming we have a document that looks like this:

	{
      "id": 24,
      "type": "airline",
      "name": "American Airlines",
      "iata": "AA",
      "icao": "AAL",
      "callsign": "AMERICAN",
      "country": "United States"
    }

We can have an associated Airline class that is symmetrical in form and shape:

[DocumentTypeFilter("airline")]
public class Airline
{
    [JsonIgnore]
    public string Id { get; set; }

    [JsonProperty("type")]
    public string Type { get; set; }

    [JsonProperty("name")]
    public string Name { get; set; }

    [JsonProperty("iata")]
    public string Iata { get; set; }

    [JsonProperty("icao")]
    public string Icao { get; set; }

    [JsonProperty("callsign")]
    public string Callsign { get; set; }

    [JsonProperty("country")]
    public string Country { get; set; }
}

Now when we generate a Linq query, the WHERE type="airline" will be automatically added to the emitted N1QL query and only document of type "airline" will be returned.

##Custom Document Filters## In addition to the default filters, custom filters are also supported which enable you to apply any predicate you wish to a POCO. To use a custom document filter, you create an implementation of IDocumentFilter which matches the criterion you wish to filter by. Here is an example of a custom filter which filters by Type:

class BreweryFilter : IDocumentFilter<Brewery>
{
    public int Priority { get; set; }

    public IQueryable<Brewery> ApplyFilter(IQueryable<Brewery> source)
    {
        return source.Where(p => p.Type == "brewery");
    }
}

Note that the predicate can be anything you wish even compound.

You have two options for applying a custom document filter. The first is to make a custom filter attribute inherited from DocumentFilterAttribute. Then apply this attribute to your document types.

The second is to register the filter using the DocumentFilterManager for each document type:

DocumentFilterManager.SetFilter<DocumentType>(new BreweryFilter());

Typically this would done when the application starts up, or you could do it in the ctor of a class which extends BucketContext.

For an example of a dynamic document filter attribute inherited from DocumentFilterAttribute, see the source code for DocumentTypeFilterAttribute.