Natural Language Mode

Connect FilterQuery to an AI/NLP endpoint so users can type filter conditions in plain English instead of query syntax.

Steps

1. Set parse="none" on the component.

With parse="none", FilterQuery does not use the built-in parser. Autocomplete and syntax highlighting are disabled. The raw typed text is delivered to your onchange handler via the text field.

<FilterQuery
  parse="none"
  placeholder="e.g., first name contains Alex and age greater than 30"
  onchange={handleFilter}
/>

2. Send the text to your AI endpoint and apply the result.

Call startProgress() before the request and endProgress() in the finally block to show the progress bar.

<script>
  import { FilterQuery, createArrayFilter } from "@svar-ui/svelte-filter";

  let data = [...]; // your dataset
  let filteredData = $state(data);

  async function handleFilter({ text, startProgress, endProgress }) {
    try {
      startProgress();
      const filterConfig = await textToFilter(text);
      if (filterConfig) {
        const filter = createArrayFilter(filterConfig);
        filteredData = filter(data);
      }
    } finally {
      endProgress();
    }
  }

  async function textToFilter(text) {
    const response = await fetch("/api/text-to-filter", {
      method: "POST",
      body: JSON.stringify({ text }),
    });
    if (!response.ok) return null;
    return response.json(); // expects the filtering rules object
  }
</script>

<FilterQuery
  parse="none"
  placeholder="e.g., first name contains Alex and age greater than 30"
  onchange={handleFilter}
/>

Your endpoint must return a set of valid filtering rule objects. Pass it directly to createArrayFilter for local filtering, or forward it to your backend.

Result: Users type natural language. When submitted, the progress bar runs while the request is in progress, and then the filtered results appear.

---

Mixed mode: query syntax with AI fallback

Use this to accept both structured queries (FirstName: *Alex*, Age: >30) and natural language descriptions. All input is routed through AI for processing.

Pass fields and options as usual. In onchange, always send the text to AI. Use getQueryString(value).query to convert the returned rules back to query syntax and write it into value. This replaces what the user typed with normalized query text.

<script>
  import { FilterQuery, createArrayFilter, getQueryString } from "@svar-ui/svelte-filter";

  const fields = [
    { id: "FirstName", label: "First Name", type: "text" },
    { id: "Age", label: "Age", type: "number" },
    { id: "Country", label: "Country", type: "text" },
  ];

  const options = {
    Country: ["USA", "Canada", "Germany"],
  };

  let textValue = $state("");
  let data = [...]; // your dataset
  let filteredData = $state(data);

  async function handleFilter({ value, error, text, startProgress, endProgress }) {
    if (text) {
      error = null;
      try {
        startProgress();
        value = await textToFilter(text, fields);
        textValue = value ? getQueryString(value).query : "";
      } catch (e) {
        error = e;
      } finally {
        endProgress();
      }
    }

    if (error) {
      console.error(error.message);
      if (error.code !== "NO_DATA") return;
    }

    const filter = createArrayFilter(value, {}, fields);
    filteredData = filter(data);
  }

  async function textToFilter(text, fields) {
    const response = await fetch("/api/text-to-filter", {
      method: "POST",
      body: JSON.stringify({ text, fields }),
    });
    if (!response.ok) throw new Error("Request failed");
    return response.json();
  }
</script>

<FilterQuery
  value={textValue}
  {fields}
  {options}
  placeholder="e.g., FirstName: contains Alex and Age: >30"
  onchange={handleFilter}
/>

Pass fields to your endpoint so the AI can map natural language to the correct field IDs.

Result: Both FirstName: *Alex* and "first name contains Alex" produce the same structured filter. After AI resolves a natural language input, the input updates to show the equivalent query syntax.

Related sample

FilterQuery: natural text