Query Preview
The query preview feature enables query extensions to provide a limited set of preview records to the builder when the query is configured. If this feature is not supported by the extension, preview records will be synthesized by the builder UI, but a preview including real live data provides a much better user experience, so if you are developing a query extension you should aim to support this feature.
Query preview is typically implemented when the underlying data provider supports some form of
top(n)
filtering. If the data provider doesn't supporttop(n)
filtering, it may be tempting to query for the entire set and throw away all records after the firstn
.The preview statement may run several times throughout configuring a query, so carefully consider the performance aspect. A maximum of 1-2s should be acceptable.
Also consider how the underlying data provider is affected by running several preview queries within a short time span. A data provider that locks a large portion of a database or performs heavy calculations may take significant load while querying, that may ultimately affect other vital operations.
If you cannot properly implement preview, but you are not satisfied with the default sample data you can implement your own synthesis within your extension, but note that the user won't have any visual indication that the data is not real.
Enable the Query Preview feature
To enable the query preview feature, configure it in the extension header file (.pyplugin/.netplugin):
Features=QueryPreview
The Query Preview feature is only supported for query extensions.
Implement the Query Preview feature
In preview mode, the number of preview records is included in the query argument to the extension ExecuteQuery()
method as the parameter _PREVIEW_COUNT_
. In a Python extension you can read it directly from ArgumentReader.PreviewCount
.
def ExecuteQuery(self, arguments, columnSchema):
argReader = ArgumentReader(arguments)
# argReader.PreviewCount will return None for non-preview executions
previewCount = argReader.PreviewCount
protected override Plugin_QueryResult ExecuteQueryImpl(List<Plugin_Argument> Parameters, Plugin_ColumnSchema ColumnSchema)
{
var paramLookup = Parameters.ToDictionary((x) => x.ParameterName);
int? previewCount = paramLookup.TryGetValue("_PREVIEW_COUNT_", out var previewCountParam)
? previewCountParam.IntegerValue
: null;
}
Preview executions are performed from the query builder. For full executions, the _PREVIEW_COUNT_
argument is omitted and ArgumentReader.PreviewCount
returns None
.
If the user sets preview row count to Unlimited, the same is true; The _PREVIEW_COUNT_
argument is omitted and ArgumentReader.PreviewCount
returns None
.
Updated 8 months ago