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 Max Query Timeout (in seconds) for the data query. 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))));
}