DFQL adapter

A grid over a DemandFlow entity

DFQL is DemandFlow's own query language, and this is the first-party adapter for it: the one that shaped the whole pushdown design. Point it at an entity with a personal access token and the grid queries it directly, so a DemandFlow entity of any size can back a grid without a service of your own in between.

import { createGrid, createPushdownSource, dfqlAdapter } from '@toclocoinc/lattice-grid';
import * as compute from '@toclocoinc/lattice-grid';

createGrid(el, {
  columns,
  rowKey: 'id',
  source: createPushdownSource({
    adapter: dfqlAdapter({
      entity: 'Ticket',
      token:  personalAccessToken,   // a DemandFlow personal access token
      query:  'SUB',                 // the key prefix to match; SUB is everything
      load:   ['id', 'status', 'owner'],   // the fields to bring back
    }),
    compute,
    pageSize: 100,
  }),
});

It is an internal integration rather than a public one. If you are not using DemandFlow, the OData, DuckDB and REST adapters are the ones to reach for.

What DFQL can and cannot do

DFQL takes a single field and term, matched as a case-insensitive substring, and that is the whole of what pushes down. There is no sort, no offset, and no operator beyond that substring match, so the adapter declares a single-term filter with the contains operator and nothing else. Everything else the grid asks for, sorting, paging, grouping, totals, is the grid's own work, done in the browser over the rows DFQL returns. This is precisely the case the pushdown design exists to handle: an engine that speaks a fraction of the query, with the grid finishing the rest correctly.

A truthful count travels with every query

DFQL has a sharp edge the adapter smooths over. Its limit caps the rows scanned, not the rows matched, so a filtered query with a limit can return an arbitrary subset, and nothing in the response says so. To make that visible, every request sends two lines in one parallel batch: the data, and a count-only line for the same query. That costs a single round trip and lets the adapter report a truthful total. The pushdown layer then compares the rows it received against that total, and if it was handed a fraction while there is work still to finish in the browser, it refuses the result and raises an error rather than filtering or sorting a fraction and presenting it as the whole.

Errors are read from inside the response, not from the status. A DFQL failure can arrive as a line in the body after a 200, so the adapter inspects the stream and surfaces it rather than trusting the status code and swallowing it.

The DFQL adapter produces an ordinary remote source, so blocks, caching and abort-on-supersede all apply. The pushdown guide explains the capability model and the split rules, and connect your data lists the other options.