# Natural Language Dataset Query (`apify/natural-language-dataset-query`) Actor

Use natural language queries to retrieve results from an Apify dataset. This Actor provides a query engine that loads a dataset, executes SQL queries, and synthesizes results. It works as an MCP (Model Context Protocol) server or REST API in Actor standby mode.

- **URL**: https://apify.com/apify/natural-language-dataset-query.md
- **Developed by:** [Apify](https://apify.com/apify) (Apify)
- **Categories:** MCP servers, AI, Open source
- **Stats:** 10 total users, 0 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-usage

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Natural Language Dataset Query

This Actor enables you to run natural language queries against an Apify dataset. For example, after running a web scraping Actor, you can ask this Actor how many pages contain a specific keyword. It supports queries via MCP ([Model Control Protocol](https://modelcontextprotocol.io)) and REST API in Standby mode, or traditional usage through the Apify Console.

> **ℹ️ Notice:**\
> This Actor internally uses the [Apify Openrouter Actor](https://apify.com/apify/openrouter) to call an LLM. You will be billed for LLM usage through this Actor.

### ⚙️ How does it work?

This Actor uses LLMs to understand your query, generate an SQL statement, and report the results. First, the Actor retrieves the dataset items and builds an internal schema representation, which is converted into an in-memory [SQLite3](https://www.sqlite.org/) database. Then, the LLM generates an SQL query and executes it against the SQLite3 database. Finally, it summarizes the results and returns them to you.

If your dataset is, for example, the result of the [RAG Web Browser](https://apify.com/apify/rag-web-browser) Actor, you can ask questions like:

- "How many pages contain the keyword 'Apify'?"

This Actor will then generate the following SQL query to retrieve that information:

```sql
SELECT COUNT(*) AS "PagesWithKeyword" FROM 'dataset' WHERE "markdown" LIKE '%apify%'
```

It will then synthesize the result into a human-readable answer, such as:

- The number of pages containing the keyword "apify" is 4.

### 🚀 Usage

#### 🟢 Normal Actor mode

You can run the Actor "normally" via the Apify API, schedule, integrations, or manually in the Apify Console. At the start, you provide input via the UI or as a JSON object and run the Actor.

> **ℹ️ Notice:**
> This mode is highly inefficient for a large number of queries against a single dataset, as the Actor will always re-fetch the dataset and rebuild the SQLite3 database. For more efficient querying, run the Actor in Standby mode.

#### 💤 Standby (REST API) mode

The Actor supports [Standby mode](https://docs.apify.com/platform/actors/running/standby), where it runs an HTTP server that processes queries on demand. This mode eliminates the need to re-fetch the dataset and rebuild the SQLite3 database for each query against a single dataset, making it much more efficient for multiple queries against the same dataset.

To run the Actor in Standby mode, send an HTTP GET request to the Actor's URL with the following query parameters:

- `dataset`: The ID of the dataset you want to query.
- `query`: The natural language query you want to run against the dataset.
- `modelName`: (optional) The name of the LLM model you want to use for the query. If not provided, the Actor will use the default model defined in the Actor input. See the Actor input schema for a list of available models. In most cases, the Google Gemini models work best for this Actor.

```text
https://natural-language-dataset-query.apify.actor/?token=YOUR_APIFY_TOKEN&dataset=DATASET_ID&query=YOUR_QUERY
```

#### 🖧 MCP server mode

You can run the Actor in MCP server mode to process queries via the MCP protocol. This enables integration with MCP clients for advanced, potentially agentic workflows.

To connect, use your MCP client and point it to:

```text
https://natural-language-dataset-query.apify.actor/mcp
```

If you are using a legacy MCP client that only supports SSE transport, you can connect to:

```text
https://natural-language-dataset-query.apify.actor/sse
```

> **ℹ️ Notice:**
> The MCP server supports OAuth authentication. If your client supports it, you can simply connect and go through the OAuth flow to authenticate. If you prefer, or if your client does not support OAuth, you need to either pass the `?token=YOUR_APIFY_TOKEN` query parameter in the request URL or set the `Authorization` header to `Bearer YOUR_APIFY_TOKEN`.

### 💸 Pricing

This Actor charges you for Apify platform compute and LLM usage, depending on the model you choose. You can verify the LLM model pricing on [OpenRouter](https://openrouter.ai/models). For a simple query, this will cost you around $0.007 per normal Actor run.

# Actor input Schema

## `query` (type: `string`):

Query for the LLM.

## `dataset` (type: `string`):

ID of the dataset to query.

## `modelName` (type: `string`):

The OpenAI model to use. Currently supported models are Gemini 2.5 Flash, Gemini 2.0 Flash, GPT-4.1, and GPT-4.1 Mini.

## `debug` (type: `boolean`):

If enabled, Actor provides detailed information with tool calls and reasoning.

## Actor input object example

```json
{
  "query": "What is the total number of pages containing the keyword 'apple'?",
  "modelName": "google/gemini-2.5-flash",
  "debug": false
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "modelName": "google/gemini-2.5-flash"
};

// Run the Actor and wait for it to finish
const run = await client.actor("apify/natural-language-dataset-query").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "modelName": "google/gemini-2.5-flash" }

# Run the Actor and wait for it to finish
run = client.actor("apify/natural-language-dataset-query").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "modelName": "google/gemini-2.5-flash"
}' |
apify call apify/natural-language-dataset-query --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,apify/natural-language-dataset-query"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/bNLFHqgWro6XnB9h7/builds/BZ3nspGyihuIRrKz3/openapi.json