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 support top(n)filtering, it may be tempting to query for the entire set and throw away all records after the first n.

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.