feat(core): search validation (#1877)

Author: dalpasso

docs/notebooks/api_user_guide/3_search.ipynb

@@ -74,6 +74,13 @@
     "}"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "A set of default values can be configured for each product type of a provider. This is configured in `providers.yml` as described in the section [\"Add a product type\"](../../add_product_type.rst). No default value is available for all ECMWF-like providers: `ecmwf`, `cop_ads`, `cop_cds`, `meteoblue`, `wekeo_ecmwf`, `dedt_lumi`, and `cop_ewds`. The [`list_queryables`](5_queryables.ipynb) method can be used to know which query parameters can be used to filter the search result."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -4148,6 +4155,7 @@
     "* `geom`\n",
     "* `locations`\n",
     "* `count`\n",
+    "* `validate`\n",
     "\n",
     "More parameters can be passed through *kwargs*, they are also described below.\n",
     "\n",
@@ -5431,6 +5439,104 @@
     "print(f\"number_matched: {results_with_count.number_matched}\")"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Validation\n",
+    "\n",
+    "The parameter `validate` can be used to automatically validate a search request before sending it to the provider. The validation is **enabled by default**."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Supported or required search parameters can be checked using [list_queryables()](./4_queryables.ipynb) method."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The following example illustrate a search request using invalid parameters.\n",
+    "Using validation, the search request returns 0 products and an exception is raised with information about the invalid or missing parameters."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 12,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "2025-10-06 18:50:37,464 eodag.core                       [INFO    ] Searching on provider cop_cds\n",
+      "2025-10-06 18:50:37,481 eodag.core                       [ERROR   ] Error while searching on provider cop_cds (ignored):\n",
+      "Traceback (most recent call last):\n",
+      "  File \"/home/ndalpasso/repos/CS-SI/eodag/eodag/plugins/search/base.py\", line 425, in validate\n",
+      "    ).get_model().model_validate(filter)\n",
+      "                  ~~~~~~~~~~~~~~^^^^^^^^\n",
+      "  File \"/home/ndalpasso/.pyenv/versions/venv-eodag-3.13/lib/python3.13/site-packages/pydantic/main.py\", line 705, in model_validate\n",
+      "    return cls.__pydantic_validator__.validate_python(\n",
+      "           ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^\n",
+      "        obj, strict=strict, from_attributes=from_attributes, context=context, by_alias=by_alias, by_name=by_name\n",
+      "        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n",
+      "    )\n",
+      "    ^\n",
+      "pydantic_core._pydantic_core.ValidationError: 2 validation errors for Queryables\n",
+      "ecmwf:variable\n",
+      "  Field required [type=missing, input_value={'productType': 'AG_ERA5'...6_00', 'geometry': None}, input_type=dict]\n",
+      "    For further information visit https://errors.pydantic.dev/2.11/v/missing\n",
+      "ecmwf:version\n",
+      "  Field required [type=missing, input_value={'productType': 'AG_ERA5'...6_00', 'geometry': None}, input_type=dict]\n",
+      "    For further information visit https://errors.pydantic.dev/2.11/v/missing\n",
+      "\n",
+      "The above exception was the direct cause of the following exception:\n",
+      "\n",
+      "Traceback (most recent call last):\n",
+      "  File \"/home/ndalpasso/repos/CS-SI/eodag/eodag/api/core.py\", line 1889, in _do_search\n",
+      "    search_plugin.validate(kwargs, prep.auth)\n",
+      "    ~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^\n",
+      "  File \"/home/ndalpasso/repos/CS-SI/eodag/eodag/plugins/search/base.py\", line 427, in validate\n",
+      "    raise ValidationError(format_pydantic_error(e)) from e\n",
+      "eodag.utils.exceptions.ValidationError: 2 error(s). ecmwf:variable: Field required; ecmwf:version: Field required\n"
+     ]
+    },
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Invalid search criteria: got a hand on 0 products.\n"
+     ]
+    }
+   ],
+   "source": [
+    "invalid_search_criteria = {\n",
+    "    \"productType\": \"AG_ERA5\",\n",
+    "    \"provider\": \"cop_cds\",\n",
+    "    \"day\": \"01\",\n",
+    "    \"month\": \"01\",\n",
+    "    \"time\": \"06_00\",\n",
+    "}\n",
+    "products = dag.search(validate=True, **invalid_search_criteria)\n",
+    "print(f\"Invalid search criteria: got a hand on {len(products)} products.\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "<div class=\"alert alert-info\">\n",
+    "\n",
+    "Note\n",
+    "\n",
+    "By default errors are not raised, only logged. See [Errors handling](./3_search.ipynb#Error-handling) and use `raise_errors=True` to raise an exception on incorrect search parameters.\n",
+    "\n",
+    "</div>"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},