Widget data query

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

Max Query Timeout

You can set a maximum query timeout (in seconds) for the data query with Enable Query Timeout, in the Loading group of the Data section. If the query takes longer than the specified duration, it will be cancelled. This is useful for preventing long-running queries from affecting page performance.

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; now it also includes 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. You can query the database or execute plugins to enrich data queries. Like the Bson syntax, the C# syntax also uses the PrimaryDataObject and DataSource concepts.

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))));
}