Skip to main content
Glama

Rechercher des lignes de données

search_data
Read-only

Retrieve dataset rows matching filters and/or full-text search. Do NOT use it to compute statistics — use datafair_aggregate_data or datafair_calculate_metric. Paginate with the "after" value returned as next.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "datasetId": "<datasetId>"
    },
    "name": "search_data"
  }
}

Input Schema

NameRequiredDescriptionDefault
bboxNoBounding box "lonMin,latMin,lonMax,latMax" (lon before lat), e.g. "-2.5,43,3,47". Geolocalized datasets only.
sizeNoLe nombre de résultats à retourner (taille de la pagination).
sortNoArray of column keys to sort by, one per element. Prefix a key with - for descending.
afterNoPagination en profondeur : la valeur à passer est celle du paramètre `after` de l'URL **next** du résultat précédent. *Automatiquement renseigné par la propriété **next** du résultat de la requête précédente.*
queryNoFull-text search across all columns. Prefer filters for structured criteria.
selectNoColumn keys to include in the response, as an array. Use column keys from datafair_describe_dataset. If omitted, all columns are returned.
filtersNoColumn filters { "<column key><suffix>": "<value as a string>" }, e.g. { "ville_eq": "Paris", "age_lte": "30", "nom_search": "Jean" }. Suffixes: _eq _neq _in _nin (comma-separated) _gt _gte _lt _lte _starts _exists _nexists _search (words, the default for text) _contains (when enabled). A rejected suffix answers a 400 listing the column's. Never prefix with _c_.
datasetIdYesThe "id" of a datafair_list_account_datasets result, not its title or slug.
dateMatchNoDate "YYYY-MM-DD" (single day) or "YYYY-MM-DD,YYYY-MM-DD" (range), e.g. "2023-11-21". Temporal datasets only.
geoDistanceNoProximity filter "lon,lat,distance" (lon first), e.g. "2.35,48.85,10km"; distance "0" = point-in-polygon. Geolocalized datasets only.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed24 schema fields changed
    • removedInput schema / $schema
      Removed value: -"http://json-schema.org/draft-07/schema#"
    • addedInput schema / properties / after
      Added value: +{
      +  "description": "Pagination en profondeur : la valeur à passer est celle du paramètre `after` de l'URL **next** du résultat précédent.\n\n*Automatiquement renseigné par la propriété **next** du résultat de la requête précédente.*",
      +  "type": "string"
      +}
    • addedInput schema / properties / bbox / examples
      Added value: +[
      +  "2.2241,48.8156,2.4699,48.9022"
      +]
    • changedInput schema / properties / datasetId / description
      Previous value: -"The exact dataset ID from the \"id\" field in list_datasets results. Do not use the title or slug."New value: +"The \"id\" of a datafair_list_account_datasets result, not its title or slug."
    • removedInput schema / properties / filters / additionalProperties
      Removed value: -{
      -  "type": "string"
      -}
    • changedInput schema / properties / filters / description
      Previous value: -"Column filters as key-value pairs: column_key + suffix, all values strings. Example: { \"ville_eq\": \"Paris\", \"age_lte\": \"30\", \"nom_search\": \"Jean\" }. Suffixes include _eq, _in, _gt/_lt, _search and more; if one is rejected the 400 error lists what the column supports. Never _c_-prefix a column filter (use ville_eq, not _c_ville_eq)."New value: +"Column filters { \"<column key><suffix>\": \"<value as a string>\" }, e.g. { \"ville_eq\": \"Paris\", \"age_lte\": \"30\", \"nom_search\": \"Jean\" }. Suffixes: _eq _neq _in _nin (comma-separated) _gt _gte _lt _lte _starts _exists _nexists _search (words, the default for text) _contains (when enabled). A rejected suffix answers a 400 listing the column's. Never prefix with _c_."
    • addedInput schema / properties / filters / patternProperties
      Added value: +{
      +  ".*": {
      +    "default": "",
      +    "type": "string"
      +  }
      +}
    • removedInput schema / properties / filters / propertyNames
      Removed value: -{
      -  "pattern": "^.+_(search|eq|neq|in|nin|starts|contains|gte?|lte?|n?exists)$"
      -}
    • removedInput schema / properties / next
      Removed value: -{
      -  "description": "URL from a previous search_data response to fetch the next page of results. When provided, all other parameters (query, filters, select, sort, size) are ignored since the URL already contains them.",
      -  "type": "string"
      -}
    • changedInput schema / properties / query / description
      Previous value: -"French keywords for full-text search across all dataset columns (simple keywords, not sentences). Can be combined with filters, but prefer filters alone when criteria target specific columns. Use query for broad keyword matching across all columns. Examples: \"Jean Dupont\", \"Paris\", \"2025\""New value: +"Full-text search across all columns. Prefer filters for structured criteria."
    • addedInput schema / properties / query / maxLength
      Added value: +1000
    • changedInput schema / properties / select / description
      Previous value: -"Optional comma-separated list of column keys to include in the results. Useful when the dataset has many columns to reduce output size. If not provided, all columns are returned. Use column keys from describe_dataset. Format: column1,column2,column3 (No spaces after commas). Example: \"nom,age,ville\""New value: +"Column keys to include in the response, as an array. Use column keys from datafair_describe_dataset. If omitted, all columns are returned."
    • addedInput schema / properties / select / items
      Added value: +{
      +  "type": "string"
      +}
    • changedInput schema / properties / select / type
      Previous value: -"string"New value: +"array"
    • addedInput schema / properties / size / default
      Added value: +12
    • changedInput schema / properties / size / description
      Previous value: -"Number of rows to return per page (default: 10, max: 50). Increase when you know you need more results upfront to avoid multiple pagination round-trips."New value: +"Le nombre de résultats à retourner (taille de la pagination)."
    • addedInput schema / properties / size / format
      Added value: +"int32"
    • addedInput schema / properties / size / maximum
      Added value: +100
    • addedInput schema / properties / size / minimum
      Added value: +0
    • changedInput schema / properties / size / type
      Previous value: -"number"New value: +"integer"
    • changedInput schema / properties / sort / description
      Previous value: -"Sort order for results. Comma-separated list of column keys. Prefix with - for descending order. Special keys: _score (relevance), _i (index order), _updatedAt, _rand (random), _geo_distance:lon:lat (distance from point, for geolocalized datasets — longitude first, then latitude). Examples: \"population\" (ascending), \"-population\" (descending), \"_geo_distance:2.35:48.85\" (closest to lon=2.35, lat=48.85)"New value: +"Array of column keys to sort by, one per element. Prefix a key with - for descending."
    • addedInput schema / properties / sort / items
      Added value: +{
      +  "type": "string"
      +}
    • changedInput schema / properties / sort / type
      Previous value: -"string"New value: +"array"
    • changedOutput schema / (root)
      Previous value: -{
      -  "$schema": "http://json-schema.org/draft-07/schema#",
      -  "additionalProperties": false,
      -  "properties": {
      -    "datasetId": {
      -      "description": "The dataset ID that was searched",
      -      "type": "string"
      -    },
      -    "filteredViewUrl": {
      -      "description": "Link to view the filtered dataset results in table format (must be included in responses for citation and direct access to filtered view)",
      -      "type": "string"
      -    },
      -    "next": {
      -      "description": "URL to fetch the next page of results. Absent when there are no more results. Pass this value as the next input parameter to get the next page.",
      -      "type": "string"
      -    },
      -    "results": {
      -      "description": "An array of data rows matching the search criteria (up to the requested size).",
      -      "items": {
      -        "additionalProperties": {},
      -        "type": "object"
      -      },
      -      "type": "array"
      -    },
      -    "total": {
      -      "description": "Number of data rows matching the search criteria and filters",
      -      "type": "number"
      -    }
      -  },
      -  "required": [
      -    "datasetId",
      -    "total",
      -    "filteredViewUrl",
      -    "results"
      -  ],
      -  "type": "object"
      -}New value: +null
  2. Changed11 schema fields changed
    • changedInput schema / properties / bbox / description
      Previous value: -"Geographic bounding box filter (only for geolocalized datasets). Format: \"lonMin,latMin,lonMax,latMax\". Example: \"-2.5,43,3,47\"."New value: +"Bounding box \"lonMin,latMin,lonMax,latMax\" (lon before lat), e.g. \"-2.5,43,3,47\". Geolocalized datasets only."
    • changedInput schema / properties / datasetId / description
      Previous value: -"The exact dataset ID from the \"id\" field in search_datasets results. Do not use the title or slug."New value: +"The exact dataset ID from the \"id\" field in list_datasets results. Do not use the title or slug."
    • changedInput schema / properties / dateMatch / description
      Previous value: -"Temporal filter (only for temporal datasets with date fields). Accepts a single date \"YYYY-MM-DD\" to match that day, or a date range \"YYYY-MM-DD,YYYY-MM-DD\" to match an overlapping period. ISO datetimes also accepted. Example: \"2023-11-21\" or \"2023-01-01,2023-12-31\"."New value: +"Date \"YYYY-MM-DD\" (single day) or \"YYYY-MM-DD,YYYY-MM-DD\" (range), e.g. \"2023-11-21\". Temporal datasets only."
    • changedInput schema / properties / filters / description
      Previous value: -"Column filters as key-value pairs. Key format: column_key + suffix (see server instructions for available suffixes). All values must be strings, even for numbers/dates. If a column key has underscores (e.g., code_postal), just append the suffix: code_postal_eq. Example: { \"nom_search\": \"Jean\", \"age_lte\": \"30\", \"ville_eq\": \"Paris\" }"New value: +"Column filters as key-value pairs: column_key + suffix, all values strings. Example: { \"ville_eq\": \"Paris\", \"age_lte\": \"30\", \"nom_search\": \"Jean\" }. Suffixes include _eq, _in, _gt/_lt, _search and more; if one is rejected the 400 error lists what the column supports. Never _c_-prefix a column filter (use ville_eq, not _c_ville_eq)."
    • changedInput schema / properties / geoDistance / description
      Previous value: -"Geographic proximity filter (only for geolocalized datasets). Restricts results to within a distance from a point. Format: \"lon,lat,distance\". Example: \"2.35,48.85,10km\". Use distance \"0\" for point-in-polygon containment."New value: +"Proximity filter \"lon,lat,distance\" (lon first), e.g. \"2.35,48.85,10km\"; distance \"0\" = point-in-polygon. Geolocalized datasets only."
    • changedInput schema / properties / sort / description
      Previous value: -"Sort order for results. Comma-separated list of column keys. Prefix with - for descending order. Special keys: _score (relevance), _i (index order), _updatedAt, _rand (random), _geo_distance:lon:lat (distance from point, for geolocalized datasets). Examples: \"population\" (ascending), \"-population\" (descending), \"_geo_distance:2.35:48.85\" (closest first)"New value: +"Sort order for results. Comma-separated list of column keys. Prefix with - for descending order. Special keys: _score (relevance), _i (index order), _updatedAt, _rand (random), _geo_distance:lon:lat (distance from point, for geolocalized datasets — longitude first, then latitude). Examples: \"population\" (ascending), \"-population\" (descending), \"_geo_distance:2.35:48.85\" (closest to lon=2.35, lat=48.85)"
    • removedOutput schema / properties / count
      Removed value: -{
      -  "description": "Number of data rows matching the search criteria and filters",
      -  "type": "number"
      -}
    • removedOutput schema / properties / lines
      Removed value: -{
      -  "description": "An array of data rows matching the search criteria (up to the requested size).",
      -  "items": {
      -    "additionalProperties": {},
      -    "description": "Data row object containing column keys as object keys with their values, plus _score field indicating search relevance (higher score = more relevant)",
      -    "type": "object"
      -  },
      -  "type": "array"
      -}
    • addedOutput schema / properties / results
      Added value: +{
      +  "description": "An array of data rows matching the search criteria (up to the requested size).",
      +  "items": {
      +    "additionalProperties": {},
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
    • addedOutput schema / properties / total
      Added value: +{
      +  "description": "Number of data rows matching the search criteria and filters",
      +  "type": "number"
      +}
    • changedOutput schema / required
      Previous value: -[
      -  "datasetId",
      -  "count",
      -  "filteredViewUrl",
      -  "lines"
      -]New value: +[
      +  "datasetId",
      +  "total",
      +  "filteredViewUrl",
      +  "results"
      +]
  3. Changed4 schema fields changed
    • addedInput schema / properties / bbox
      Added value: +{
      +  "description": "Geographic bounding box filter (only for geolocalized datasets). Format: \"lonMin,latMin,lonMax,latMax\". Example: \"-2.5,43,3,47\".",
      +  "type": "string"
      +}
    • addedInput schema / properties / dateMatch
      Added value: +{
      +  "description": "Temporal filter (only for temporal datasets with date fields). Accepts a single date \"YYYY-MM-DD\" to match that day, or a date range \"YYYY-MM-DD,YYYY-MM-DD\" to match an overlapping period. ISO datetimes also accepted. Example: \"2023-11-21\" or \"2023-01-01,2023-12-31\".",
      +  "type": "string"
      +}
    • addedInput schema / properties / geoDistance
      Added value: +{
      +  "description": "Geographic proximity filter (only for geolocalized datasets). Restricts results to within a distance from a point. Format: \"lon,lat,distance\". Example: \"2.35,48.85,10km\". Use distance \"0\" for point-in-polygon containment.",
      +  "type": "string"
      +}
    • changedInput schema / properties / sort / description
      Previous value: -"Sort order for results. Comma-separated list of column keys. Prefix with - for descending order. Special keys: _score (relevance), _i (index order), _updatedAt, _rand (random). Examples: \"population\" (ascending), \"-population\" (descending), \"city,-population\" (city asc then population desc)"New value: +"Sort order for results. Comma-separated list of column keys. Prefix with - for descending order. Special keys: _score (relevance), _i (index order), _updatedAt, _rand (random), _geo_distance:lon:lat (distance from point, for geolocalized datasets). Examples: \"population\" (ascending), \"-population\" (descending), \"_geo_distance:2.35:48.85\" (closest first)"
  4. Changed5 schema fields changed
    • changedInput schema / properties / datasetId / description
      Previous value: -"The unique dataset ID obtained from search_datasets or provided by the user"New value: +"The exact dataset ID from the \"id\" field in search_datasets results. Do not use the title or slug."
    • changedInput schema / properties / filters / description
      Previous value: -"Column filters as key-value pairs. Key format: column_key + suffix (see server instructions for available suffixes). Example: { \"nom_search\": \"Jean\", \"age_lte\": \"30\", \"ville_eq\": \"Paris\" }"New value: +"Column filters as key-value pairs. Key format: column_key + suffix (see server instructions for available suffixes). All values must be strings, even for numbers/dates. If a column key has underscores (e.g., code_postal), just append the suffix: code_postal_eq. Example: { \"nom_search\": \"Jean\", \"age_lte\": \"30\", \"ville_eq\": \"Paris\" }"
    • changedInput schema / properties / next / description
      Previous value: -"URL from a previous search_data response to fetch the next page of results. When provided, all other parameters (query, filters, select, size) are ignored since the URL already contains them."New value: +"URL from a previous search_data response to fetch the next page of results. When provided, all other parameters (query, filters, select, sort, size) are ignored since the URL already contains them."
    • changedInput schema / properties / query / description
      Previous value: -"French keywords for full-text search across all dataset columns (simple keywords, not sentences). Do not use with filters parameter. Examples: \"Jean Dupont\", \"Paris\", \"2025\""New value: +"French keywords for full-text search across all dataset columns (simple keywords, not sentences). Can be combined with filters, but prefer filters alone when criteria target specific columns. Use query for broad keyword matching across all columns. Examples: \"Jean Dupont\", \"Paris\", \"2025\""
    • addedInput schema / properties / sort
      Added value: +{
      +  "description": "Sort order for results. Comma-separated list of column keys. Prefix with - for descending order. Special keys: _score (relevance), _i (index order), _updatedAt, _rand (random). Examples: \"population\" (ascending), \"-population\" (descending), \"city,-population\" (city asc then population desc)",
      +  "type": "string"
      +}
  5. First observed

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description contributes the pagination behavior — that continuation is driven by the 'after' value taken from the returned next URL. It doesn't discuss result ordering guarantees or what happens with an expired cursor, but that is minor against annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, all front-loaded: capability first, the exclusion/alternative second, the pagination mechanic last. No filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a ten-parameter search tool this covers the core purpose, the main misuse risk, and how to page; with no output schema present, the brief mention of the returned next value partially covers the response. A note that results are row objects limited by size would close the remaining gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all ten parameters, including bbox, geoDistance, dateMatch and filter suffixes, are already documented in the schema. The description's only parameter-adjacent content is the 'after'/'next' pagination pointer, which is also stated in the schema, so it adds little beyond structured fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (retrieve dataset rows) plus the two qualifying mechanisms (filters, full-text search), and explicitly contrasts itself with the aggregation/metric siblings. An agent can distinguish it from aggregate_data and calculate_metric without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit 'do NOT use for statistics' exclusion naming the two alternatives to use instead, which is exactly the routing decision this tool needs. It lacks guidance on other neighbors (e.g., when to call describe_dataset first to get column keys), so it stops short of full when/when-not coverage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources