Widget data query

When configuring a data widget such as a grid widget or list widget, you will need to instruct Casewhere how to load data from a data source by composing a data query. Casewhere supports two types of query syntaxes: Bson and C#.

Bson data query

Bson is the default query syntax, which is sufficient for most cases.

{ 
	"PrimaryDataObject": { CaseState: "Created" }, 
	"DataSource": {} 
}

• PrimaryDataObject: Filter on the data source's primary data class. Filtering on the primary data class is generally fast because Casewhere can utilize database indexes to speed up the queries.

• DataSource: Filter on the data source projected fields. Casewhere cannot utilize database indexes for this kind of filter, so it's not recommended to use on a large data source.

Keywords

@user: The user in context. You can learn more about the user data object here.

{
	"PrimaryDataObject": { CaseState: "Created", CreatedBy: "{{@user.UserId}}" }, 
	"DataSource": {} 
}

Params: The widget parameters sent from worker sites. You can learn how to set the parameters here.

Then the data query will be:

{
	"PrimaryDataObject": { CaseState: "Created", Author: "{{Params.Author}}" }, 
	"DataSource": {} 
}

Examples

The book data source has below fields:

{
    Id,
    CreatedBy,
    Title,
    Description,
    Author,
    Year,
    ...
}

To get a specific book by its ID

{ 
	"PrimaryDataObject": { CaseState: "Created", _id: "{{Params.Id}}" }, 
	"DataSource": {} 
}

To get books created by the logged-in user

{ 
	"PrimaryDataObject": { CaseState: "Created", CreatedBy: "{{@user.UserId}}" }, 
	"DataSource": {} 
}

Let's extend the book data source a bit, now it also has the library's information.

{
    Id,
    CreatedBy,
    Title,
    Description,
    Author,
    Year,
    Library: {
        Id,
        Name,
        ...
    },
    ...
}

To get books in the Library of Congress:

{ 
	"PrimaryDataObject": { CaseState: "Created" }, 
	"DataSource": { "Library.Name": "Library of Congress" }
}

C# data query

This syntax is designed to handle the most complex scenarios. Here you can query the database or even execute plugins to get more information to enrich the data queries. Similar to the Bson syntax, the C# syntax also has the two concepts PrimaryDataObject and DataSource.

var primaryDataObject = Filter["PrimaryDataObject"].AsBsonDocument;
var dataSource = Filter["DataSource"].AsBsonDocument;

primaryDataObject.Add(new BsonDocument("CaseState", "Created"));

Keywords

@user: The user in context. You can learn more about the user data object here.

var primaryDataObject = Filter["PrimaryDataObject"].AsBsonDocument;
var dataSource = Filter["DataSource"].AsBsonDocument;

primaryDataObject.Add(new BsonDocument("CaseState", "Created"));
primaryDataObject.Add(new BsonDocument("CreatedBy", @user.UserId);

@parameters: The widget parameters sent from worker sites. You can learn how to set the parameters here.

var primaryDataObject = Filter["PrimaryDataObject"].AsBsonDocument;
var dataSource = Filter["DataSource"].AsBsonDocument;

primaryDataObject.Add(new BsonDocument("CaseState", "Created"));
primaryDataObject.Add(new BsonDocument("Author", @parameters.Get<string>("Author")));

@apiFactory: To construct Casewhere API objects. Read here for the full list of available Apis.

var dataApi = @apiFactory.Get<IDataApi>();  
var pluginApi = @apiFactory.Get<IPluginApi>();  
var documentApi = @apiFactory.Get<IDocumentApi>();  
var cacheApi = @apiFactory.Get<ICacheApi>(); 
... 

Examples

Assume you have a data source in the below structure:

{
    Id,
    CreatedBy,
    Title,
    Description,
    Author,
    Year,
    Library: {
        Id,
        Name,
        ...
    },

    ...
}

To get a specific book by its ID

var primaryDataObject = Filter["PrimaryDataObject"].AsBsonDocument;
var dataSource = Filter["DataSource"].AsBsonDocument;

primaryDataObject.Add(new BsonDocument("CaseState", "Created"));
primaryDataObject.Add(new BsonDocument("_id", @parameters.Get<string>("Id")));

If the Id parameter is not provided, load all books. Else, load the book by its Id.

var primaryDataObject = Filter["PrimaryDataObject"].AsBsonDocument;
var dataSource = Filter["DataSource"].AsBsonDocument;

primaryDataObject.Add(new BsonDocument("CaseState", "Created"));
if (@parameters.Has("Id"))
{
    primaryDataObject.Add(new BsonDocument("_id", @parameters.Get<string>("Id")));
}

To get books created by the logged-in user

var primaryDataObject = Filter["PrimaryDataObject"].AsBsonDocument;
var dataSource = Filter["DataSource"].AsBsonDocument;

primaryDataObject.Add(new BsonDocument("CaseState", "Created"));
primaryDataObject.Add(new BsonDocument("CreatedBy", @user.UserId));

To get books in the Library of Congress:

var primaryDataObject = Filter["PrimaryDataObject"].AsBsonDocument;
var dataSource = Filter["DataSource"].AsBsonDocument;

primaryDataObject.Add(new BsonDocument("CaseState", "Created"));
dataSource.Add(new BsonDocument("Library.Name", "Library of Congress"));

To find books at all libraries in Denmark:

var primaryDataObject = Filter["PrimaryDataObject"].AsBsonDocument;
var dataSource = Filter["DataSource"].AsBsonDocument;

primaryDataObject.Add(new BsonDocument("CaseState", "Created"));

var dataApi = @apiFactory.Get<IDataApi>();
var libraryFilter = FilterBuilder
    .Create()
    .Eq("Country", "DK")
    .Build();

var libraries = dataApi.Search(DataObjectApiQuery
    .For("Library")
    .FilterBy(libraryFilter)).Data;

var libraryIds = libraries.Select(lib => lib.Get<string>("Id")).ToList();

if (libraryIds.Count > 0)
{
    primaryDataObject.Add(new BsonDocument("LibraryId", new BsonDocument("$in", new BsonArray(libraryIds))));
}