Types

Main types

pydantic model app._types.AggregateSearchParameters

Show JSON schema

{
   "title": "AggregateSearchParameters",
   "type": "object",
   "properties": {
      "facets": {
         "anyOf": [
            {
               "items": {
                  "type": "string"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Name of facets to return in the response as a comma-separated value.\nIf None (default) no facets are returned.",
         "title": "Facets"
      },
      "charts": {
         "anyOf": [
            {
               "items": {
                  "anyOf": [
                     {
                        "$ref": "#/$defs/DistributionChart"
                     },
                     {
                        "$ref": "#/$defs/ScatterChart"
                     }
                  ]
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Name of vega representations to return in the response.\nCan be distribution chart or scatter plot.\n\nIf you pass a simple string, it will be interpreted as a distribution chart,\nor a scatter plot if it is two fields separated by a column (x_axis_field:y_axis_field).",
         "title": "Charts"
      }
   },
   "$defs": {
      "DistributionChart": {
         "description": "Describes an entry for a distribution chart",
         "properties": {
            "chart_type": {
               "const": "DistributionChart",
               "default": "DistributionChart",
               "enum": [
                  "DistributionChart"
               ],
               "title": "Chart Type",
               "type": "string"
            },
            "field": {
               "title": "Field",
               "type": "string"
            }
         },
         "required": [
            "field"
         ],
         "title": "DistributionChart",
         "type": "object"
      },
      "ScatterChart": {
         "description": "Describes an entry for a scatter plot",
         "properties": {
            "chart_type": {
               "const": "ScatterChart",
               "default": "ScatterChart",
               "enum": [
                  "ScatterChart"
               ],
               "title": "Chart Type",
               "type": "string"
            },
            "x": {
               "title": "X",
               "type": "string"
            },
            "y": {
               "title": "Y",
               "type": "string"
            }
         },
         "required": [
            "x",
            "y"
         ],
         "title": "ScatterChart",
         "type": "object"
      }
   }
}

Fields:

• charts (list[app._types.DistributionChart | app._types.ScatterChart] | None)

• facets (list[str] | None)

Validators:

• check_charts_are_valid » all fields

• check_facets_are_valid » all fields

field charts: Annotated[list[DistributionChart | ScatterChart] | None, Query(PydanticUndefined)] = None

Name of vega representations to return in the response. Can be distribution chart or scatter plot.

If you pass a simple string, it will be interpreted as a distribution chart, or a scatter plot if it is two fields separated by a column (x_axis_field:y_axis_field).

Validated by:

• check_charts_are_valid

• check_facets_are_valid

field facets: Annotated[list[str] | None, Query(PydanticUndefined)] = None

Name of facets to return in the response as a comma-separated value. If None (default) no facets are returned.

Validated by:

• check_charts_are_valid

• check_facets_are_valid

validator check_charts_are_valid  »  all fields

Check that the graph names are valid.

validator check_facets_are_valid  »  all fields

Check that the facets names are valid.

property sign_sort_by: Tuple[Literal['+', '-'], str | None]

app._types.ChartsInfos

Information about charts for a search result

alias of dict[str, dict[str, Any]]

class app._types.CommonParametersQuery

Documentation and constraints for some common query parameters

class app._types.DebugInfo(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Debug information to return in the API

pydantic model app._types.DistributionChart

Describes an entry for a distribution chart

Show JSON schema

{
   "title": "DistributionChart",
   "description": "Describes an entry for a distribution chart",
   "type": "object",
   "properties": {
      "chart_type": {
         "const": "DistributionChart",
         "default": "DistributionChart",
         "enum": [
            "DistributionChart"
         ],
         "title": "Chart Type",
         "type": "string"
      },
      "field": {
         "title": "Field",
         "type": "string"
      }
   },
   "required": [
      "field"
   ]
}

Fields:

• chart_type (Literal['DistributionChart'])

• field (str)

field chart_type: Literal['DistributionChart'] = 'DistributionChart'

field field: str [Required]

pydantic model app._types.ErrorSearchResponse

Show JSON schema

{
   "title": "ErrorSearchResponse",
   "type": "object",
   "properties": {
      "debug": {
         "$ref": "#/$defs/SearchResponseDebug"
      },
      "errors": {
         "items": {
            "$ref": "#/$defs/SearchResponseError"
         },
         "title": "Errors",
         "type": "array"
      }
   },
   "$defs": {
      "SearchResponseDebug": {
         "properties": {
            "lucene_query": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Lucene Query"
            },
            "es_query": {
               "anyOf": [
                  {
                     "type": "object"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Es Query"
            },
            "aggregations": {
               "anyOf": [
                  {
                     "type": "object"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Aggregations"
            }
         },
         "title": "SearchResponseDebug",
         "type": "object"
      },
      "SearchResponseError": {
         "properties": {
            "title": {
               "title": "Title",
               "type": "string"
            },
            "description": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Description"
            }
         },
         "required": [
            "title"
         ],
         "title": "SearchResponseError",
         "type": "object"
      }
   },
   "required": [
      "debug",
      "errors"
   ]
}

Fields:

• debug (app._types.SearchResponseDebug)

• errors (list[app._types.SearchResponseError])

field debug: SearchResponseDebug [Required]

field errors: list[SearchResponseError] [Required]

is_success()

pydantic model app._types.FacetInfo

Search result for a facet

Show JSON schema

{
   "title": "FacetInfo",
   "description": "Search result for a facet",
   "type": "object",
   "properties": {
      "name": {
         "title": "Name",
         "type": "string"
      },
      "items": {
         "items": {
            "$ref": "#/$defs/FacetItem"
         },
         "title": "Items",
         "type": "array"
      },
      "count_error_margin": {
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Count Error Margin"
      }
   },
   "$defs": {
      "FacetItem": {
         "description": "Describes an entry of a facet",
         "properties": {
            "key": {
               "title": "Key",
               "type": "string"
            },
            "name": {
               "title": "Name",
               "type": "string"
            },
            "count": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "title": "Count"
            },
            "selected": {
               "title": "Selected",
               "type": "boolean"
            }
         },
         "required": [
            "key",
            "name",
            "count",
            "selected"
         ],
         "title": "FacetItem",
         "type": "object"
      }
   },
   "required": [
      "name",
      "items"
   ]
}

Fields:

• count_error_margin (int | None)

• items (list[app._types.FacetItem])

• name (str)

field count_error_margin: int | None = None

field items: list[FacetItem] [Required]

Items in the facets

field name: str [Required]

The display name of the facet

pydantic model app._types.FacetItem

Describes an entry of a facet

Show JSON schema

{
   "title": "FacetItem",
   "description": "Describes an entry of a facet",
   "type": "object",
   "properties": {
      "key": {
         "title": "Key",
         "type": "string"
      },
      "name": {
         "title": "Name",
         "type": "string"
      },
      "count": {
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "title": "Count"
      },
      "selected": {
         "title": "Selected",
         "type": "boolean"
      }
   },
   "required": [
      "key",
      "name",
      "count",
      "selected"
   ]
}

Fields:

• count (int | None)

• key (str)

• name (str)

• selected (bool)

field count: int | None [Required]

The number of elements for this value

field key: str [Required]

field name: str [Required]

field selected: bool [Required]

Whether this value is selected

app._types.FacetsFilters

Data about selected filters for each facet: facet name -> list of values

alias of dict[str, list[str]]

app._types.FacetsInfos

Information about facets for a search result

alias of dict[str, FacetInfo]

pydantic model app._types.FetcherResult

Result for a document fetcher

This is also used by pre-processors who have the opportunity to discard an entry

Show JSON schema

{
   "title": "FetcherResult",
   "description": "Result for a document fetcher\n\nThis is also used by pre-processors\nwho have the opportunity to discard an entry",
   "type": "object",
   "properties": {
      "status": {
         "$ref": "#/$defs/FetcherStatus"
      },
      "document": {
         "anyOf": [
            {
               "type": "object"
            },
            {
               "type": "null"
            }
         ],
         "title": "Document"
      }
   },
   "$defs": {
      "FetcherStatus": {
         "description": "Status of a fetcher\n\n* FOUND - document was found, index it\n* REMOVED - document was removed, remove it\n* SKIP - skip this document / update\n* RETRY - retry this document / update later\n* OTHER - unknown error",
         "enum": [
            1,
            -1,
            0,
            2,
            3
         ],
         "title": "FetcherStatus",
         "type": "integer"
      }
   },
   "required": [
      "status",
      "document"
   ]
}

Fields:

• document (dict[str, Any] | None)

• status (app._types.FetcherStatus)

field document: dict[str, Any] | None [Required]

field status: FetcherStatus [Required]

class app._types.FetcherStatus(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Status of a fetcher

• FOUND - document was found, index it

• REMOVED - document was removed, remove it

• SKIP - skip this document / update

• RETRY - retry this document / update later

• OTHER - unknown error

pydantic model app._types.GetSearchParameters

GET parameters for search

Show JSON schema

{
   "title": "GetSearchParameters",
   "description": "GET parameters for search",
   "type": "object",
   "properties": {
      "facets": {
         "anyOf": [
            {
               "items": {
                  "type": "string"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Name of facets to return in the response as a comma-separated value.\nIf None (default) no facets are returned.",
         "title": "Facets"
      },
      "charts": {
         "anyOf": [
            {
               "items": {
                  "anyOf": [
                     {
                        "$ref": "#/$defs/DistributionChart"
                     },
                     {
                        "$ref": "#/$defs/ScatterChart"
                     }
                  ]
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Name of vega representations to return in the response.\nCan be distribution chart or scatter plot.\n\nIf you pass a simple string, it will be interpreted as a distribution chart,\nor a scatter plot if it is two fields separated by a column (x_axis_field:y_axis_field).",
         "title": "Charts"
      },
      "fields": {
         "anyOf": [
            {
               "items": {
                  "type": "string"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "List of fields to include in the response. All other fields will be ignored.",
         "title": "Fields"
      },
      "page_size": {
         "default": 10,
         "description": "Number of results to return per page.",
         "title": "Page Size",
         "type": "integer"
      },
      "page": {
         "default": 1,
         "description": "Number of results to return per page.",
         "title": "Page",
         "type": "integer"
      },
      "sort_by": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Field name to use to sort results,\nthe field should exist and be sortable.\nIf it is not provided, results are sorted by descending relevance score.\n(aka best match)\n\nIf you put a minus before the name, the results will be sorted by descending order.\n\nIf the field name match a known script (defined in your configuration),\nit will be use for sorting.\n\nIn this case you also need to provide additional parameters corresponding to your script parameters.\nIf a script needs parameters, you can only use the POST method.\n\nBeware that this may have a big [impact on performance][perf_link]\n\nAlso bare in mind [privacy considerations][privacy_link] if your script parameters contains sensible data.\n\n[perf_link]: https://openfoodfacts.github.io/search-a-licious/users/how-to-use-scripts/#performance-considerations\n[privacy_link]: https://openfoodfacts.github.io/search-a-licious/users/how-to-use-scripts/#performance-considerations",
         "title": "Sort By"
      },
      "q": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The search query, it supports Lucene search query\nsyntax (https://lucene.apache.org/core/3_6_0/queryparsersyntax.html). Words\nthat are not recognized by the lucene query parser are searched as full text\nsearch.\n\nExample: `categories_tags:\"en:beverages\" strawberry brands:\"casino\"` query use a\nfilter clause for categories and brands and look for \"strawberry\" in multiple\nfields.\n\nThe query is optional, but `sort_by` value must then be provided.",
         "title": "Q"
      },
      "boost_phrase": {
         "default": false,
         "description": "This enables an heuristic that will favor,\nmatching terms that are consecutive.\n\nTechnically, if you have a query with the two words `whole milk`\nit will boost entries with `\"whole milk\"` exact match.\nThe boost factor is defined by `match_phrase_boost` value in Configuration\n\nNote, that it only make sense if you use best match sorting.\nSo in any other case it is ignored.",
         "title": "Boost Phrase",
         "type": "boolean"
      },
      "langs": {
         "default": [
            "en"
         ],
         "description": "List of languages we want to support during search.\nThis list should include the user expected language, and additional languages (such\nas english for example).\n\nThis is currently used for language-specific subfields to choose in which\nsubfields we're searching in.\n\nIf not provided, `['en']` is used.",
         "items": {
            "type": "string"
         },
         "title": "Langs",
         "type": "array"
      },
      "index_id": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Index ID to use for the search, if not provided, the default index is used.\nIf there is only one index, this parameter is not needed.",
         "title": "Index Id"
      },
      "debug_info": {
         "anyOf": [
            {
               "items": {
                  "$ref": "#/$defs/DebugInfo"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Tells which debug information to return in the response.\nIt can be a comma separated list of values",
         "title": "Debug Info"
      }
   },
   "$defs": {
      "DebugInfo": {
         "description": "Debug information to return in the API",
         "enum": [
            "aggregations",
            "lucene_query",
            "es_query"
         ],
         "title": "DebugInfo",
         "type": "string"
      },
      "DistributionChart": {
         "description": "Describes an entry for a distribution chart",
         "properties": {
            "chart_type": {
               "const": "DistributionChart",
               "default": "DistributionChart",
               "enum": [
                  "DistributionChart"
               ],
               "title": "Chart Type",
               "type": "string"
            },
            "field": {
               "title": "Field",
               "type": "string"
            }
         },
         "required": [
            "field"
         ],
         "title": "DistributionChart",
         "type": "object"
      },
      "ScatterChart": {
         "description": "Describes an entry for a scatter plot",
         "properties": {
            "chart_type": {
               "const": "ScatterChart",
               "default": "ScatterChart",
               "enum": [
                  "ScatterChart"
               ],
               "title": "Chart Type",
               "type": "string"
            },
            "x": {
               "title": "X",
               "type": "string"
            },
            "y": {
               "title": "Y",
               "type": "string"
            }
         },
         "required": [
            "x",
            "y"
         ],
         "title": "ScatterChart",
         "type": "object"
      }
   },
   "additionalProperties": false
}

Config:

• extra: str = forbid

Fields:

Validators:

• no_sort_by_scripts_on_get » all fields

• parse_charts_str » charts

• parse_value_str » facets

• parse_value_str » fields

• validate_q_or_sort_by » all fields

validator no_sort_by_scripts_on_get  »  all fields

validator parse_charts_str  »  charts

Parse for get params are ‘field’ or ‘xfield:yfield’ separated by ‘,’ for Distribution and Scatter charts.

Directly the dictionnaries in POST request

validator parse_value_str  »  facets, fields

Parse for get params ‘langs’

validator validate_q_or_sort_by  »  all fields

We want at least one of q or sort_by before launching a request

app._types.JSONType

A precise expectation of what mappings looks like in json. (dict where keys are always of type str).

alias of dict[str, Any]

pydantic model app._types.PostSearchParameters

POST parameters for search

Show JSON schema

{
   "title": "PostSearchParameters",
   "description": "POST parameters for search",
   "type": "object",
   "properties": {
      "facets": {
         "anyOf": [
            {
               "items": {
                  "type": "string"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Name of facets to return in the response as a comma-separated value.\nIf None (default) no facets are returned.",
         "title": "Facets"
      },
      "charts": {
         "anyOf": [
            {
               "items": {
                  "anyOf": [
                     {
                        "$ref": "#/$defs/DistributionChart"
                     },
                     {
                        "$ref": "#/$defs/ScatterChart"
                     }
                  ]
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Name of vega representations to return in the response.\nCan be distribution chart or scatter plot.\n\nIf you pass a simple string, it will be interpreted as a distribution chart,\nor a scatter plot if it is two fields separated by a column (x_axis_field:y_axis_field).",
         "title": "Charts"
      },
      "fields": {
         "anyOf": [
            {
               "items": {
                  "type": "string"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "List of fields to include in the response. All other fields will be ignored.",
         "title": "Fields"
      },
      "page_size": {
         "default": 10,
         "description": "Number of results to return per page.",
         "title": "Page Size",
         "type": "integer"
      },
      "page": {
         "default": 1,
         "description": "Number of results to return per page.",
         "title": "Page",
         "type": "integer"
      },
      "sort_by": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Field name to use to sort results,\nthe field should exist and be sortable.\nIf it is not provided, results are sorted by descending relevance score.\n(aka best match)\n\nIf you put a minus before the name, the results will be sorted by descending order.\n\nIf the field name match a known script (defined in your configuration),\nit will be use for sorting.\n\nIn this case you also need to provide additional parameters corresponding to your script parameters.\nIf a script needs parameters, you can only use the POST method.\n\nBeware that this may have a big [impact on performance][perf_link]\n\nAlso bare in mind [privacy considerations][privacy_link] if your script parameters contains sensible data.\n\n[perf_link]: https://openfoodfacts.github.io/search-a-licious/users/how-to-use-scripts/#performance-considerations\n[privacy_link]: https://openfoodfacts.github.io/search-a-licious/users/how-to-use-scripts/#performance-considerations",
         "title": "Sort By"
      },
      "q": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The search query, it supports Lucene search query\nsyntax (https://lucene.apache.org/core/3_6_0/queryparsersyntax.html). Words\nthat are not recognized by the lucene query parser are searched as full text\nsearch.\n\nExample: `categories_tags:\"en:beverages\" strawberry brands:\"casino\"` query use a\nfilter clause for categories and brands and look for \"strawberry\" in multiple\nfields.\n\nThe query is optional, but `sort_by` value must then be provided.",
         "title": "Q"
      },
      "boost_phrase": {
         "default": false,
         "description": "This enables an heuristic that will favor,\nmatching terms that are consecutive.\n\nTechnically, if you have a query with the two words `whole milk`\nit will boost entries with `\"whole milk\"` exact match.\nThe boost factor is defined by `match_phrase_boost` value in Configuration\n\nNote, that it only make sense if you use best match sorting.\nSo in any other case it is ignored.",
         "title": "Boost Phrase",
         "type": "boolean"
      },
      "langs": {
         "default": [
            "en"
         ],
         "description": "List of languages we want to support during search.\nThis list should include the user expected language, and additional languages (such\nas english for example).\n\nThis is currently used for language-specific subfields to choose in which\nsubfields we're searching in.\n\nIf not provided, `['en']` is used.",
         "items": {
            "type": "string"
         },
         "title": "Langs",
         "type": "array"
      },
      "index_id": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Index ID to use for the search, if not provided, the default index is used.\nIf there is only one index, this parameter is not needed.",
         "title": "Index Id"
      },
      "debug_info": {
         "anyOf": [
            {
               "items": {
                  "$ref": "#/$defs/DebugInfo"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Tells which debug information to return in the response.\nIt can be a comma separated list of values",
         "title": "Debug Info"
      },
      "sort_params": {
         "anyOf": [
            {
               "type": "object"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Additional parameters when using  a sort script in sort_by.\nIf the sort script needs parameters, you can only be used the POST method.",
         "title": "Sort Params"
      }
   },
   "$defs": {
      "DebugInfo": {
         "description": "Debug information to return in the API",
         "enum": [
            "aggregations",
            "lucene_query",
            "es_query"
         ],
         "title": "DebugInfo",
         "type": "string"
      },
      "DistributionChart": {
         "description": "Describes an entry for a distribution chart",
         "properties": {
            "chart_type": {
               "const": "DistributionChart",
               "default": "DistributionChart",
               "enum": [
                  "DistributionChart"
               ],
               "title": "Chart Type",
               "type": "string"
            },
            "field": {
               "title": "Field",
               "type": "string"
            }
         },
         "required": [
            "field"
         ],
         "title": "DistributionChart",
         "type": "object"
      },
      "ScatterChart": {
         "description": "Describes an entry for a scatter plot",
         "properties": {
            "chart_type": {
               "const": "ScatterChart",
               "default": "ScatterChart",
               "enum": [
                  "ScatterChart"
               ],
               "title": "Chart Type",
               "type": "string"
            },
            "x": {
               "title": "X",
               "type": "string"
            },
            "y": {
               "title": "Y",
               "type": "string"
            }
         },
         "required": [
            "x",
            "y"
         ],
         "title": "ScatterChart",
         "type": "object"
      }
   },
   "additionalProperties": false
}

Config:

• extra: str = forbid

Fields:

• sort_params (Annotated[dict[str, Any] | None, Query(PydanticUndefined)])

Validators:

• sort_by_scripts_needs_params » all fields

field sort_params: Annotated[dict[str, Any] | None, Query(PydanticUndefined)] = None

Additional parameters when using a sort script in sort_by. If the sort script needs parameters, you can only be used the POST method.

Validated by:

• check_charts_are_valid

• check_facets_are_valid

• check_max_results

• sort_by_is_field_or_script

• sort_by_scripts_needs_params

• validate_index_id

validator sort_by_scripts_needs_params  »  all fields

If sort_by is a script, verify we got corresponding parameters in sort_params

pydantic model app._types.QuerySearchParameters

Parameters for search, this class concentrates on parameters that define the search query

Show JSON schema

{
   "title": "QuerySearchParameters",
   "description": "Parameters for search,\nthis class concentrates on parameters that define the search query",
   "type": "object",
   "properties": {
      "q": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The search query, it supports Lucene search query\nsyntax (https://lucene.apache.org/core/3_6_0/queryparsersyntax.html). Words\nthat are not recognized by the lucene query parser are searched as full text\nsearch.\n\nExample: `categories_tags:\"en:beverages\" strawberry brands:\"casino\"` query use a\nfilter clause for categories and brands and look for \"strawberry\" in multiple\nfields.\n\nThe query is optional, but `sort_by` value must then be provided.",
         "title": "Q"
      },
      "boost_phrase": {
         "default": false,
         "description": "This enables an heuristic that will favor,\nmatching terms that are consecutive.\n\nTechnically, if you have a query with the two words `whole milk`\nit will boost entries with `\"whole milk\"` exact match.\nThe boost factor is defined by `match_phrase_boost` value in Configuration\n\nNote, that it only make sense if you use best match sorting.\nSo in any other case it is ignored.",
         "title": "Boost Phrase",
         "type": "boolean"
      },
      "langs": {
         "default": [
            "en"
         ],
         "description": "List of languages we want to support during search.\nThis list should include the user expected language, and additional languages (such\nas english for example).\n\nThis is currently used for language-specific subfields to choose in which\nsubfields we're searching in.\n\nIf not provided, `['en']` is used.",
         "items": {
            "type": "string"
         },
         "title": "Langs",
         "type": "array"
      },
      "index_id": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Index ID to use for the search, if not provided, the default index is used.\nIf there is only one index, this parameter is not needed.",
         "title": "Index Id"
      }
   }
}

Fields:

• boost_phrase (bool)

• index_id (str | None)

• langs (list[str])

• q (str | None)

Validators:

• check_max_results » all fields

• parse_langs_str » langs

• validate_index_id » all fields

field boost_phrase: Annotated[bool, Query(PydanticUndefined)] = False

This enables an heuristic that will favor, matching terms that are consecutive.

Technically, if you have a query with the two words whole milk it will boost entries with “whole milk” exact match. The boost factor is defined by match_phrase_boost value in Configuration

Note, that it only make sense if you use best match sorting. So in any other case it is ignored.

Validated by:

• check_max_results

• validate_index_id

field index_id: Annotated[str | None, Query(PydanticUndefined)] = None

Index ID to use for the search, if not provided, the default index is used. If there is only one index, this parameter is not needed.

Validated by:

• check_max_results

• validate_index_id

field langs: Annotated[list[str], Query(PydanticUndefined)] = ['en']

List of languages we want to support during search. This list should include the user expected language, and additional languages (such as english for example).

This is currently used for language-specific subfields to choose in which subfields we’re searching in.

If not provided, [‘en’] is used.

Validated by:

• check_max_results

• parse_langs_str

• validate_index_id

field q: Annotated[str | None, Query(PydanticUndefined)] = None

The search query, it supports Lucene search query syntax (https://lucene.apache.org/core/3_6_0/queryparsersyntax.html). Words that are not recognized by the lucene query parser are searched as full text search.

Example: categories_tags:”en:beverages” strawberry brands:”casino” query use a filter clause for categories and brands and look for “strawberry” in multiple fields.

The query is optional, but sort_by value must then be provided.

Validated by:

• check_max_results

• validate_index_id

validator check_max_results  »  all fields

Check we don’t ask too many results at once

validator parse_langs_str  »  langs

Parse for get params ‘langs’

validator validate_index_id  »  all fields

Validate index_id is known, or use default index if not provided

We call this validator as a model validator, because we want to be able to substitute the default None value, by the default index

property index_config

Get the index config once and for all

property langs_set

property main_lang

Get the main lang of the query

property valid_index_id: str

Give a not None index_id

This is mainly to avoid typing errors

pydantic model app._types.ResultSearchParameters

Parameters that influence results presentation: pagination and sorting

Show JSON schema

{
   "title": "ResultSearchParameters",
   "description": "Parameters that influence results presentation: pagination and sorting",
   "type": "object",
   "properties": {
      "fields": {
         "anyOf": [
            {
               "items": {
                  "type": "string"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "List of fields to include in the response. All other fields will be ignored.",
         "title": "Fields"
      },
      "page_size": {
         "default": 10,
         "description": "Number of results to return per page.",
         "title": "Page Size",
         "type": "integer"
      },
      "page": {
         "default": 1,
         "description": "Number of results to return per page.",
         "title": "Page",
         "type": "integer"
      },
      "sort_by": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Field name to use to sort results,\nthe field should exist and be sortable.\nIf it is not provided, results are sorted by descending relevance score.\n(aka best match)\n\nIf you put a minus before the name, the results will be sorted by descending order.\n\nIf the field name match a known script (defined in your configuration),\nit will be use for sorting.\n\nIn this case you also need to provide additional parameters corresponding to your script parameters.\nIf a script needs parameters, you can only use the POST method.\n\nBeware that this may have a big [impact on performance][perf_link]\n\nAlso bare in mind [privacy considerations][privacy_link] if your script parameters contains sensible data.\n\n[perf_link]: https://openfoodfacts.github.io/search-a-licious/users/how-to-use-scripts/#performance-considerations\n[privacy_link]: https://openfoodfacts.github.io/search-a-licious/users/how-to-use-scripts/#performance-considerations",
         "title": "Sort By"
      }
   }
}

Fields:

• fields (list[str] | None)

• page (int)

• page_size (int)

• sort_by (str | None)

Validators:

• sort_by_is_field_or_script » all fields

field fields: Annotated[list[str] | None, Query(PydanticUndefined)] = None

List of fields to include in the response. All other fields will be ignored.

Validated by:

• sort_by_is_field_or_script

field page: Annotated[int, Query(PydanticUndefined)] = 1

Number of results to return per page.

Validated by:

• sort_by_is_field_or_script

field page_size: Annotated[int, Query(PydanticUndefined)] = 10

Number of results to return per page.

Validated by:

• sort_by_is_field_or_script

field sort_by: Annotated[str | None, Query(PydanticUndefined)] = None

Field name to use to sort results, the field should exist and be sortable. If it is not provided, results are sorted by descending relevance score. (aka best match)

If you put a minus before the name, the results will be sorted by descending order.

If the field name match a known script (defined in your configuration), it will be use for sorting.

In this case you also need to provide additional parameters corresponding to your script parameters. If a script needs parameters, you can only use the POST method.

Beware that this may have a big [impact on performance][perf_link]

Also bare in mind [privacy considerations][privacy_link] if your script parameters contains sensible data.

[perf_link]: https://openfoodfacts.github.io/search-a-licious/users/how-to-use-scripts/#performance-considerations [privacy_link]: https://openfoodfacts.github.io/search-a-licious/users/how-to-use-scripts/#performance-considerations

Validated by:

• sort_by_is_field_or_script

validator sort_by_is_field_or_script  »  all fields

Verify sort_by is a valid field or script name

property uses_sort_script

Does sort_by use a script?

pydantic model app._types.ScatterChart

Describes an entry for a scatter plot

Show JSON schema

{
   "title": "ScatterChart",
   "description": "Describes an entry for a scatter plot",
   "type": "object",
   "properties": {
      "chart_type": {
         "const": "ScatterChart",
         "default": "ScatterChart",
         "enum": [
            "ScatterChart"
         ],
         "title": "Chart Type",
         "type": "string"
      },
      "x": {
         "title": "X",
         "type": "string"
      },
      "y": {
         "title": "Y",
         "type": "string"
      }
   },
   "required": [
      "x",
      "y"
   ]
}

Fields:

• chart_type (Literal['ScatterChart'])

• x (str)

• y (str)

field chart_type: Literal['ScatterChart'] = 'ScatterChart'

field x: str [Required]

field y: str [Required]

pydantic model app._types.SearchParameters

Parameters for search, common to GET and POST

Show JSON schema

{
   "title": "SearchParameters",
   "description": "Parameters for search, common to GET and POST",
   "type": "object",
   "properties": {
      "facets": {
         "anyOf": [
            {
               "items": {
                  "type": "string"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Name of facets to return in the response as a comma-separated value.\nIf None (default) no facets are returned.",
         "title": "Facets"
      },
      "charts": {
         "anyOf": [
            {
               "items": {
                  "anyOf": [
                     {
                        "$ref": "#/$defs/DistributionChart"
                     },
                     {
                        "$ref": "#/$defs/ScatterChart"
                     }
                  ]
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Name of vega representations to return in the response.\nCan be distribution chart or scatter plot.\n\nIf you pass a simple string, it will be interpreted as a distribution chart,\nor a scatter plot if it is two fields separated by a column (x_axis_field:y_axis_field).",
         "title": "Charts"
      },
      "fields": {
         "anyOf": [
            {
               "items": {
                  "type": "string"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "List of fields to include in the response. All other fields will be ignored.",
         "title": "Fields"
      },
      "page_size": {
         "default": 10,
         "description": "Number of results to return per page.",
         "title": "Page Size",
         "type": "integer"
      },
      "page": {
         "default": 1,
         "description": "Number of results to return per page.",
         "title": "Page",
         "type": "integer"
      },
      "sort_by": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Field name to use to sort results,\nthe field should exist and be sortable.\nIf it is not provided, results are sorted by descending relevance score.\n(aka best match)\n\nIf you put a minus before the name, the results will be sorted by descending order.\n\nIf the field name match a known script (defined in your configuration),\nit will be use for sorting.\n\nIn this case you also need to provide additional parameters corresponding to your script parameters.\nIf a script needs parameters, you can only use the POST method.\n\nBeware that this may have a big [impact on performance][perf_link]\n\nAlso bare in mind [privacy considerations][privacy_link] if your script parameters contains sensible data.\n\n[perf_link]: https://openfoodfacts.github.io/search-a-licious/users/how-to-use-scripts/#performance-considerations\n[privacy_link]: https://openfoodfacts.github.io/search-a-licious/users/how-to-use-scripts/#performance-considerations",
         "title": "Sort By"
      },
      "q": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The search query, it supports Lucene search query\nsyntax (https://lucene.apache.org/core/3_6_0/queryparsersyntax.html). Words\nthat are not recognized by the lucene query parser are searched as full text\nsearch.\n\nExample: `categories_tags:\"en:beverages\" strawberry brands:\"casino\"` query use a\nfilter clause for categories and brands and look for \"strawberry\" in multiple\nfields.\n\nThe query is optional, but `sort_by` value must then be provided.",
         "title": "Q"
      },
      "boost_phrase": {
         "default": false,
         "description": "This enables an heuristic that will favor,\nmatching terms that are consecutive.\n\nTechnically, if you have a query with the two words `whole milk`\nit will boost entries with `\"whole milk\"` exact match.\nThe boost factor is defined by `match_phrase_boost` value in Configuration\n\nNote, that it only make sense if you use best match sorting.\nSo in any other case it is ignored.",
         "title": "Boost Phrase",
         "type": "boolean"
      },
      "langs": {
         "default": [
            "en"
         ],
         "description": "List of languages we want to support during search.\nThis list should include the user expected language, and additional languages (such\nas english for example).\n\nThis is currently used for language-specific subfields to choose in which\nsubfields we're searching in.\n\nIf not provided, `['en']` is used.",
         "items": {
            "type": "string"
         },
         "title": "Langs",
         "type": "array"
      },
      "index_id": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Index ID to use for the search, if not provided, the default index is used.\nIf there is only one index, this parameter is not needed.",
         "title": "Index Id"
      },
      "debug_info": {
         "anyOf": [
            {
               "items": {
                  "$ref": "#/$defs/DebugInfo"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Tells which debug information to return in the response.\nIt can be a comma separated list of values",
         "title": "Debug Info"
      }
   },
   "$defs": {
      "DebugInfo": {
         "description": "Debug information to return in the API",
         "enum": [
            "aggregations",
            "lucene_query",
            "es_query"
         ],
         "title": "DebugInfo",
         "type": "string"
      },
      "DistributionChart": {
         "description": "Describes an entry for a distribution chart",
         "properties": {
            "chart_type": {
               "const": "DistributionChart",
               "default": "DistributionChart",
               "enum": [
                  "DistributionChart"
               ],
               "title": "Chart Type",
               "type": "string"
            },
            "field": {
               "title": "Field",
               "type": "string"
            }
         },
         "required": [
            "field"
         ],
         "title": "DistributionChart",
         "type": "object"
      },
      "ScatterChart": {
         "description": "Describes an entry for a scatter plot",
         "properties": {
            "chart_type": {
               "const": "ScatterChart",
               "default": "ScatterChart",
               "enum": [
                  "ScatterChart"
               ],
               "title": "Chart Type",
               "type": "string"
            },
            "x": {
               "title": "X",
               "type": "string"
            },
            "y": {
               "title": "Y",
               "type": "string"
            }
         },
         "required": [
            "x",
            "y"
         ],
         "title": "ScatterChart",
         "type": "object"
      }
   },
   "additionalProperties": false
}

Config:

• extra: str = forbid

Fields:

• debug_info (Annotated[list[app._types.DebugInfo] | None, Query(PydanticUndefined)])

Validators:

• debug_info_list_from_str » debug_info

field debug_info: Annotated[list[DebugInfo] | None, Query(PydanticUndefined)] = None

Tells which debug information to return in the response. It can be a comma separated list of values

Validated by:

• check_charts_are_valid

• check_facets_are_valid

• check_max_results

• debug_info_list_from_str

• sort_by_is_field_or_script

• validate_index_id

validator debug_info_list_from_str  »  debug_info

We can pass a comma separated list of DebugInfo values as a string

pydantic model app._types.SearchResponseDebug

Show JSON schema

{
   "title": "SearchResponseDebug",
   "type": "object",
   "properties": {
      "lucene_query": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Lucene Query"
      },
      "es_query": {
         "anyOf": [
            {
               "type": "object"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Es Query"
      },
      "aggregations": {
         "anyOf": [
            {
               "type": "object"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Aggregations"
      }
   }
}

Fields:

• aggregations (dict[str, Any] | None)

• es_query (dict[str, Any] | None)

• lucene_query (str | None)

field aggregations: dict[str, Any] | None = None

field es_query: dict[str, Any] | None = None

field lucene_query: str | None = None

pydantic model app._types.SearchResponseError

Show JSON schema

{
   "title": "SearchResponseError",
   "type": "object",
   "properties": {
      "title": {
         "title": "Title",
         "type": "string"
      },
      "description": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Description"
      }
   },
   "required": [
      "title"
   ]
}

Fields:

• description (str | None)

• title (str)

field description: str | None = None

field title: str [Required]

pydantic model app._types.SuccessSearchResponse

Show JSON schema

{
   "title": "SuccessSearchResponse",
   "type": "object",
   "properties": {
      "hits": {
         "items": {
            "type": "object"
         },
         "title": "Hits",
         "type": "array"
      },
      "aggregations": {
         "anyOf": [
            {
               "type": "object"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Aggregations"
      },
      "facets": {
         "anyOf": [
            {
               "additionalProperties": {
                  "$ref": "#/$defs/FacetInfo"
               },
               "type": "object"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Facets"
      },
      "charts": {
         "anyOf": [
            {
               "additionalProperties": {
                  "type": "object"
               },
               "type": "object"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Charts"
      },
      "page": {
         "title": "Page",
         "type": "integer"
      },
      "page_size": {
         "title": "Page Size",
         "type": "integer"
      },
      "page_count": {
         "title": "Page Count",
         "type": "integer"
      },
      "debug": {
         "anyOf": [
            {
               "$ref": "#/$defs/SearchResponseDebug"
            },
            {
               "type": "null"
            }
         ],
         "default": null
      },
      "took": {
         "title": "Took",
         "type": "integer"
      },
      "timed_out": {
         "title": "Timed Out",
         "type": "boolean"
      },
      "count": {
         "title": "Count",
         "type": "integer"
      },
      "is_count_exact": {
         "title": "Is Count Exact",
         "type": "boolean"
      },
      "warnings": {
         "anyOf": [
            {
               "items": {
                  "$ref": "#/$defs/SearchResponseError"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Warnings"
      }
   },
   "$defs": {
      "FacetInfo": {
         "description": "Search result for a facet",
         "properties": {
            "name": {
               "title": "Name",
               "type": "string"
            },
            "items": {
               "items": {
                  "$ref": "#/$defs/FacetItem"
               },
               "title": "Items",
               "type": "array"
            },
            "count_error_margin": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Count Error Margin"
            }
         },
         "required": [
            "name",
            "items"
         ],
         "title": "FacetInfo",
         "type": "object"
      },
      "FacetItem": {
         "description": "Describes an entry of a facet",
         "properties": {
            "key": {
               "title": "Key",
               "type": "string"
            },
            "name": {
               "title": "Name",
               "type": "string"
            },
            "count": {
               "anyOf": [
                  {
                     "type": "integer"
                  },
                  {
                     "type": "null"
                  }
               ],
               "title": "Count"
            },
            "selected": {
               "title": "Selected",
               "type": "boolean"
            }
         },
         "required": [
            "key",
            "name",
            "count",
            "selected"
         ],
         "title": "FacetItem",
         "type": "object"
      },
      "SearchResponseDebug": {
         "properties": {
            "lucene_query": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Lucene Query"
            },
            "es_query": {
               "anyOf": [
                  {
                     "type": "object"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Es Query"
            },
            "aggregations": {
               "anyOf": [
                  {
                     "type": "object"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Aggregations"
            }
         },
         "title": "SearchResponseDebug",
         "type": "object"
      },
      "SearchResponseError": {
         "properties": {
            "title": {
               "title": "Title",
               "type": "string"
            },
            "description": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Description"
            }
         },
         "required": [
            "title"
         ],
         "title": "SearchResponseError",
         "type": "object"
      }
   },
   "required": [
      "hits",
      "page",
      "page_size",
      "page_count",
      "took",
      "timed_out",
      "count",
      "is_count_exact"
   ]
}

Fields:

• aggregations (dict[str, Any] | None)

• charts (dict[str, dict[str, Any]] | None)

• count (int)

• debug (app._types.SearchResponseDebug | None)

• facets (dict[str, app._types.FacetInfo] | None)

• hits (list[dict[str, Any]])

• is_count_exact (bool)

• page (int)

• page_count (int)

• page_size (int)

• timed_out (bool)

• took (int)

• warnings (list[app._types.SearchResponseError] | None)

field aggregations: dict[str, Any] | None = None

field charts: dict[str, dict[str, Any]] | None = None

field count: int [Required]

field debug: SearchResponseDebug | None = None

field facets: dict[str, FacetInfo] | None = None

field hits: list[dict[str, Any]] [Required]

field is_count_exact: bool [Required]

field page: int [Required]

field page_count: int [Required]

field page_size: int [Required]

field timed_out: bool [Required]

field took: int [Required]

field warnings: list[SearchResponseError] | None = None

is_success()

pydantic model app._types.QueryAnalysis

An object containing different information about the query.

Config:

• arbitrary_types_allowed: bool = True

Fields:

• es_query (elasticsearch_dsl.query.Query | None)

• facets_filters (dict[str, list[str]] | None)

• luqum_tree (luqum.tree.Item | None)

• text_query (str | None)

field es_query: Query | None = None

The query as an elasticsearch_dsl object

field facets_filters: dict[str, list[str]] | None = None

The filters corresponding to the facets: a facet name and a list of values

field luqum_tree: Item | None = None

The luqum tree corresponding to the text query

field text_query: str | None = None

The initial text query

clone(**kwargs)

class app._types.QueryAnalysis(*, text_query: str | None = None, luqum_tree: Item | None = None, es_query: Query | None = None, facets_filters: dict[str, list[str]] | None = None)

An object containing different information about the query.

field es_query: Query | None = None

The query as an elasticsearch_dsl object

field facets_filters: dict[str, list[str]] | None = None

The filters corresponding to the facets: a facet name and a list of values

field luqum_tree: Item | None = None

The luqum tree corresponding to the text query

model_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[dict[str, FieldInfo]] = {'es_query': FieldInfo(annotation=Union[Query, NoneType], required=False, default=None), 'facets_filters': FieldInfo(annotation=Union[dict[str, list[str]], NoneType], required=False, default=None), 'luqum_tree': FieldInfo(annotation=Union[Item, NoneType], required=False, default=None), 'text_query': FieldInfo(annotation=Union[str, NoneType], required=False, default=None)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo].

This replaces Model.__fields__ from Pydantic V1.

field text_query: str | None = None

The initial text query

Validations

app.validations.check_all_values_are_fields_agg(index_id: str | None, values: list[str] | None) → list[str]

Check that all values are fields with aggregate: true property, that is, correspond to a field with aggregation. Used to check that charts are facets are valid.

app.validations.check_fields_are_numeric(index_id: str | None, values: list[str] | None) → list[str]

• If field exists in global_config, check that it’s numeric.

• If field looks like x.y and x.y does not exist in global config, check that x is an object field

app.validations.check_index_id_is_defined(index_id: str | None, config: Config) → None

Check that the index ID is defined in the configuration.

Raise an HTTPException if it’s not the case.

Parameters:

• index_id – index ID to check

• config – configuration to check against