Skip to content

elasticsearch

__all__ = ('ElasticTransformer') module-attribute

BaseResourceMapper

Generic Resource Mapper that defines and performs the mapping between objects in the database and the resource objects defined by the specification.

Attributes:

Name Type Description
ALIASES tuple[tuple[str, str], ...]

a tuple of aliases between OPTIMADE field names and the field names in the database , e.g. (("elements", "custom_elements_field")).
LENGTH_ALIASES tuple[tuple[str, str], ...]

a tuple of aliases between a field name and another field that defines its length, to be used when querying, e.g. (("elements", "nelements")). e.g. (("elements", "custom_elements_field")).
ENTRY_RESOURCE_CLASS type[EntryResource]

The entry type that this mapper corresponds to.
PROVIDER_FIELDS tuple[str, ...]

a tuple of extra field names that this mapper should support when querying with the database prefix.
TOP_LEVEL_NON_ATTRIBUTES_FIELDS set[str]

the set of top-level field names common to all endpoints.
SUPPORTED_PREFIXES set[str]

The set of prefixes registered by this mapper.
ALL_ATTRIBUTES set[str]

The set of attributes defined across the entry resource class and the server configuration.
ENTRY_RESOURCE_ATTRIBUTES dict[str, Any]

A dictionary of attributes and their definitions defined by the schema of the entry resource class.
ENDPOINT str

The expected endpoint name for this resource, as defined by the type in the schema of the entry resource class.
Source code in optimade/server/mappers/entries.py 
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
class BaseResourceMapper:
    """Generic Resource Mapper that defines and performs the mapping
    between objects in the database and the resource objects defined by
    the specification.

    Attributes:
        ALIASES: a tuple of aliases between
            OPTIMADE field names and the field names in the database ,
            e.g. `(("elements", "custom_elements_field"))`.
        LENGTH_ALIASES: a tuple of aliases between
            a field name and another field that defines its length, to be used
            when querying, e.g. `(("elements", "nelements"))`.
            e.g. `(("elements", "custom_elements_field"))`.
        ENTRY_RESOURCE_CLASS: The entry type that this mapper corresponds to.
        PROVIDER_FIELDS: a tuple of extra field names that this
            mapper should support when querying with the database prefix.
        TOP_LEVEL_NON_ATTRIBUTES_FIELDS: the set of top-level
            field names common to all endpoints.
        SUPPORTED_PREFIXES: The set of prefixes registered by this mapper.
        ALL_ATTRIBUTES: The set of attributes defined across the entry
            resource class and the server configuration.
        ENTRY_RESOURCE_ATTRIBUTES: A dictionary of attributes and their definitions
            defined by the schema of the entry resource class.
        ENDPOINT: The expected endpoint name for this resource, as defined by
            the `type` in the schema of the entry resource class.

    """

    try:
        from optimade.server.data import providers as PROVIDERS  # type: ignore
    except (ImportError, ModuleNotFoundError):
        PROVIDERS = {}

    KNOWN_PROVIDER_PREFIXES: set[str] = {
        prov["id"] for prov in PROVIDERS.get("data", [])
    }
    ALIASES: tuple[tuple[str, str], ...] = ()
    LENGTH_ALIASES: tuple[tuple[str, str], ...] = ()
    PROVIDER_FIELDS: tuple[str, ...] = ()
    ENTRY_RESOURCE_CLASS: type[EntryResource] = EntryResource
    RELATIONSHIP_ENTRY_TYPES: set[str] = {"references", "structures"}
    TOP_LEVEL_NON_ATTRIBUTES_FIELDS: set[str] = {"id", "type", "relationships", "links"}

    @classmethod
    @lru_cache(maxsize=NUM_ENTRY_TYPES)
    def all_aliases(cls) -> Iterable[tuple[str, str]]:
        """Returns all of the associated aliases for this entry type,
        including those defined by the server config. The first member
        of each tuple is the OPTIMADE-compliant field name, the second
        is the backend-specific field name.

        Returns:
            A tuple of alias tuples.

        """
        from optimade.server.config import CONFIG

        return (
            tuple(
                (f"_{CONFIG.provider.prefix}_{field}", field)
                if not field.startswith("_")
                else (field, field)
                for field in CONFIG.provider_fields.get(cls.ENDPOINT, [])
                if isinstance(field, str)
            )
            + tuple(
                (f"_{CONFIG.provider.prefix}_{field['name']}", field["name"])
                if not field["name"].startswith("_")
                else (field["name"], field["name"])
                for field in CONFIG.provider_fields.get(cls.ENDPOINT, [])
                if isinstance(field, dict)
            )
            + tuple(
                (f"_{CONFIG.provider.prefix}_{field}", field)
                if not field.startswith("_")
                else (field, field)
                for field in cls.PROVIDER_FIELDS
            )
            + tuple(CONFIG.aliases.get(cls.ENDPOINT, {}).items())
            + cls.ALIASES
        )

    @classproperty
    @lru_cache(maxsize=1)
    def SUPPORTED_PREFIXES(cls) -> set[str]:
        """A set of prefixes handled by this entry type.

        !!! note
            This implementation only includes the provider prefix,
            but in the future this property may be extended to include other
            namespaces (for serving fields from, e.g., other providers or
            domain-specific terms).

        """
        from optimade.server.config import CONFIG

        return {CONFIG.provider.prefix}

    @classproperty
    def ALL_ATTRIBUTES(cls) -> set[str]:
        """Returns all attributes served by this entry."""
        from optimade.server.config import CONFIG

        return (
            set(cls.ENTRY_RESOURCE_ATTRIBUTES)
            .union(
                cls.get_optimade_field(field)
                for field in CONFIG.provider_fields.get(cls.ENDPOINT, ())
                if isinstance(field, str)
            )
            .union(
                cls.get_optimade_field(field["name"])
                for field in CONFIG.provider_fields.get(cls.ENDPOINT, ())
                if isinstance(field, dict)
            )
            .union({cls.get_optimade_field(field) for field in cls.PROVIDER_FIELDS})
        )

    @classproperty
    def ENTRY_RESOURCE_ATTRIBUTES(cls) -> dict[str, Any]:
        """Returns the dictionary of attributes defined by the underlying entry resource class."""
        from optimade.server.schemas import retrieve_queryable_properties

        return retrieve_queryable_properties(cls.ENTRY_RESOURCE_CLASS)

    @classproperty
    @lru_cache(maxsize=NUM_ENTRY_TYPES)
    def ENDPOINT(cls) -> str:
        """Returns the expected endpoint for this mapper, corresponding
        to the `type` property of the resource class.

        """
        endpoint = cls.ENTRY_RESOURCE_CLASS.model_fields["type"].default
        if not endpoint and not isinstance(endpoint, str):
            raise ValueError("Type not set for this entry type!")
        return endpoint

    @classmethod
    @lru_cache(maxsize=NUM_ENTRY_TYPES)
    def all_length_aliases(cls) -> tuple[tuple[str, str], ...]:
        """Returns all of the associated length aliases for this class,
        including those defined by the server config.

        Returns:
            A tuple of length alias tuples.

        """
        from optimade.server.config import CONFIG

        return cls.LENGTH_ALIASES + tuple(
            CONFIG.length_aliases.get(cls.ENDPOINT, {}).items()
        )

    @classmethod
    @lru_cache(maxsize=128)
    def length_alias_for(cls, field: str) -> Optional[str]:
        """Returns the length alias for the particular field,
        or `None` if no such alias is found.

        Parameters:
            field: OPTIMADE field name.

        Returns:
            Aliased field as found in [`all_length_aliases()`][optimade.server.mappers.entries.BaseResourceMapper.all_length_aliases].

        """
        return dict(cls.all_length_aliases()).get(field, None)

    @classmethod
    @lru_cache(maxsize=128)
    def get_backend_field(cls, optimade_field: str) -> str:
        """Return the field name configured for the particular
        underlying database for the passed OPTIMADE field name, that would
        be used in an API filter.

        Aliases are read from
        [`all_aliases()`][optimade.server.mappers.entries.BaseResourceMapper.all_aliases].

        If a dot-separated OPTIMADE field is provided, e.g., `species.mass`, only the first part will be mapped.
        This means for an (OPTIMADE, DB) alias of (`species`, `kinds`), `get_backend_fields("species.mass")`
        will return `kinds.mass`.

        Arguments:
            optimade_field: The OPTIMADE field to attempt to map to the backend-specific field.

        Examples:
            >>> get_backend_field("chemical_formula_anonymous")
            'formula_anon'
            >>> get_backend_field("formula_anon")
            'formula_anon'
            >>> get_backend_field("_exmpl_custom_provider_field")
            'custom_provider_field'

        Returns:
            The mapped field name to be used in the query to the backend.

        """
        split = optimade_field.split(".")
        alias = dict(cls.all_aliases()).get(split[0], None)
        if alias is not None:
            return alias + ("." + ".".join(split[1:]) if len(split) > 1 else "")
        return optimade_field

    @classmethod
    @lru_cache(maxsize=128)
    def alias_for(cls, field: str) -> str:
        """Return aliased field name.

        !!! warning "Deprecated"
            This method is deprecated could be removed without further warning. Please use
            [`get_backend_field()`][optimade.server.mappers.entries.BaseResourceMapper.get_backend_field].

        Parameters:
            field: OPTIMADE field name.

        Returns:
            Aliased field as found in [`all_aliases()`][optimade.server.mappers.entries.BaseResourceMapper.all_aliases].

        """
        warnings.warn(
            "The `.alias_for(...)` method is deprecated, please use `.get_backend_field(...)`.",
            DeprecationWarning,
        )
        return cls.get_backend_field(field)

    @classmethod
    @lru_cache(maxsize=128)
    def get_optimade_field(cls, backend_field: str) -> str:
        """Return the corresponding OPTIMADE field name for the underlying database field,
        ready to be used to construct the OPTIMADE-compliant JSON response.

        Aliases are read from
        [`all_aliases()`][optimade.server.mappers.entries.BaseResourceMapper.all_aliases].

        Arguments:
            backend_field: The backend field to attempt to map to an OPTIMADE field.

        Examples:
            >>> get_optimade_field("chemical_formula_anonymous")
            'chemical_formula_anonymous'
            >>> get_optimade_field("formula_anon")
            'chemical_formula_anonymous'
            >>> get_optimade_field("custom_provider_field")
            '_exmpl_custom_provider_field'

        Returns:
            The mapped field name to be used in an OPTIMADE-compliant response.

        """
        return {alias: real for real, alias in cls.all_aliases()}.get(
            backend_field, backend_field
        )

    @classmethod
    @lru_cache(maxsize=128)
    def alias_of(cls, field: str) -> str:
        """Return de-aliased field name, if it exists,
        otherwise return the input field name.

        !!! warning "Deprecated"
            This method is deprecated could be removed without further warning. Please use
            [`get_optimade_field()`][optimade.server.mappers.entries.BaseResourceMapper.get_optimade_field].

        Parameters:
            field: Field name to be de-aliased.

        Returns:
            De-aliased field name, falling back to returning `field`.

        """
        warnings.warn(
            "The `.alias_of(...)` method is deprecated, please use `.get_optimade_field(...)`.",
            DeprecationWarning,
        )
        return cls.get_optimade_field(field)

    @classmethod
    @lru_cache(maxsize=NUM_ENTRY_TYPES)
    def get_required_fields(cls) -> set:
        """Get REQUIRED response fields.

        Returns:
            REQUIRED response fields.

        """
        return cls.TOP_LEVEL_NON_ATTRIBUTES_FIELDS

    @classmethod
    def map_back(cls, doc: dict) -> dict:
        """Map properties from MongoDB to OPTIMADE.

        Starting from a MongoDB document `doc`, map the DB fields to the corresponding OPTIMADE fields.
        Then, the fields are all added to the top-level field "attributes",
        with the exception of other top-level fields, defined in `cls.TOP_LEVEL_NON_ATTRIBUTES_FIELDS`.
        All fields not in `cls.TOP_LEVEL_NON_ATTRIBUTES_FIELDS` + "attributes" will be removed.
        Finally, the `type` is given the value of the specified `cls.ENDPOINT`.

        Parameters:
            doc: A resource object in MongoDB format.

        Returns:
            A resource object in OPTIMADE format.

        """
        mapping = ((real, alias) for alias, real in cls.all_aliases())
        newdoc = {}
        reals = {real for _, real in cls.all_aliases()}
        for key in doc:
            if key not in reals:
                newdoc[key] = doc[key]
        for real, alias in mapping:
            if real in doc:
                newdoc[alias] = doc[real]

        if "attributes" in newdoc:
            raise Exception("Will overwrite doc field!")
        attributes = newdoc.copy()

        for field in cls.TOP_LEVEL_NON_ATTRIBUTES_FIELDS:
            value = attributes.pop(field, None)
            if value is not None:
                newdoc[field] = value
        for field in list(newdoc.keys()):
            if field not in cls.TOP_LEVEL_NON_ATTRIBUTES_FIELDS:
                del newdoc[field]

        newdoc["type"] = cls.ENDPOINT
        newdoc["attributes"] = attributes

        return newdoc

    @classmethod
    def deserialize(
        cls, results: Union[dict, Iterable[dict]]
    ) -> Union[list[EntryResource], EntryResource]:
        """Converts the raw database entries for this class into serialized models,
        mapping the data along the way.

        """
        if isinstance(results, dict):
            return cls.ENTRY_RESOURCE_CLASS(**cls.map_back(results))

        return [cls.ENTRY_RESOURCE_CLASS(**cls.map_back(doc)) for doc in results]

ALL_ATTRIBUTES()

Returns all attributes served by this entry.

Source code in optimade/server/mappers/entries.py 
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
@classproperty
def ALL_ATTRIBUTES(cls) -> set[str]:
    """Returns all attributes served by this entry."""
    from optimade.server.config import CONFIG

    return (
        set(cls.ENTRY_RESOURCE_ATTRIBUTES)
        .union(
            cls.get_optimade_field(field)
            for field in CONFIG.provider_fields.get(cls.ENDPOINT, ())
            if isinstance(field, str)
        )
        .union(
            cls.get_optimade_field(field["name"])
            for field in CONFIG.provider_fields.get(cls.ENDPOINT, ())
            if isinstance(field, dict)
        )
        .union({cls.get_optimade_field(field) for field in cls.PROVIDER_FIELDS})
    )

ENDPOINT() cached

Returns the expected endpoint for this mapper, corresponding to the type property of the resource class.

Source code in optimade/server/mappers/entries.py 
161
162
163
164
165
166
167
168
169
170
171
@classproperty
@lru_cache(maxsize=NUM_ENTRY_TYPES)
def ENDPOINT(cls) -> str:
    """Returns the expected endpoint for this mapper, corresponding
    to the `type` property of the resource class.

    """
    endpoint = cls.ENTRY_RESOURCE_CLASS.model_fields["type"].default
    if not endpoint and not isinstance(endpoint, str):
        raise ValueError("Type not set for this entry type!")
    return endpoint

ENTRY_RESOURCE_ATTRIBUTES()

Returns the dictionary of attributes defined by the underlying entry resource class.

Source code in optimade/server/mappers/entries.py 
154
155
156
157
158
159
@classproperty
def ENTRY_RESOURCE_ATTRIBUTES(cls) -> dict[str, Any]:
    """Returns the dictionary of attributes defined by the underlying entry resource class."""
    from optimade.server.schemas import retrieve_queryable_properties

    return retrieve_queryable_properties(cls.ENTRY_RESOURCE_CLASS)

SUPPORTED_PREFIXES() cached

A set of prefixes handled by this entry type.

Note

This implementation only includes the provider prefix, but in the future this property may be extended to include other namespaces (for serving fields from, e.g., other providers or domain-specific terms).

Source code in optimade/server/mappers/entries.py 
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
@classproperty
@lru_cache(maxsize=1)
def SUPPORTED_PREFIXES(cls) -> set[str]:
    """A set of prefixes handled by this entry type.

    !!! note
        This implementation only includes the provider prefix,
        but in the future this property may be extended to include other
        namespaces (for serving fields from, e.g., other providers or
        domain-specific terms).

    """
    from optimade.server.config import CONFIG

    return {CONFIG.provider.prefix}

alias_for(field) cached classmethod

Return aliased field name.

Deprecated

This method is deprecated could be removed without further warning. Please use get_backend_field().

Parameters:

Name Type Description Default
field str

OPTIMADE field name.

 required

Returns:

Type Description
str

Aliased field as found in all_aliases().
Source code in optimade/server/mappers/entries.py 
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
@classmethod
@lru_cache(maxsize=128)
def alias_for(cls, field: str) -> str:
    """Return aliased field name.

    !!! warning "Deprecated"
        This method is deprecated could be removed without further warning. Please use
        [`get_backend_field()`][optimade.server.mappers.entries.BaseResourceMapper.get_backend_field].

    Parameters:
        field: OPTIMADE field name.

    Returns:
        Aliased field as found in [`all_aliases()`][optimade.server.mappers.entries.BaseResourceMapper.all_aliases].

    """
    warnings.warn(
        "The `.alias_for(...)` method is deprecated, please use `.get_backend_field(...)`.",
        DeprecationWarning,
    )
    return cls.get_backend_field(field)

alias_of(field) cached classmethod

Return de-aliased field name, if it exists, otherwise return the input field name.

Deprecated

This method is deprecated could be removed without further warning. Please use get_optimade_field().

Parameters:

Name Type Description Default
field str

Field name to be de-aliased.

 required

Returns:

Type Description
str

De-aliased field name, falling back to returning field.
Source code in optimade/server/mappers/entries.py 
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
@classmethod
@lru_cache(maxsize=128)
def alias_of(cls, field: str) -> str:
    """Return de-aliased field name, if it exists,
    otherwise return the input field name.

    !!! warning "Deprecated"
        This method is deprecated could be removed without further warning. Please use
        [`get_optimade_field()`][optimade.server.mappers.entries.BaseResourceMapper.get_optimade_field].

    Parameters:
        field: Field name to be de-aliased.

    Returns:
        De-aliased field name, falling back to returning `field`.

    """
    warnings.warn(
        "The `.alias_of(...)` method is deprecated, please use `.get_optimade_field(...)`.",
        DeprecationWarning,
    )
    return cls.get_optimade_field(field)

all_aliases() cached classmethod

Returns all of the associated aliases for this entry type, including those defined by the server config. The first member of each tuple is the OPTIMADE-compliant field name, the second is the backend-specific field name.

Returns:

Type Description
Iterable[tuple[str, str]]

A tuple of alias tuples.
Source code in optimade/server/mappers/entries.py 
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
@classmethod
@lru_cache(maxsize=NUM_ENTRY_TYPES)
def all_aliases(cls) -> Iterable[tuple[str, str]]:
    """Returns all of the associated aliases for this entry type,
    including those defined by the server config. The first member
    of each tuple is the OPTIMADE-compliant field name, the second
    is the backend-specific field name.

    Returns:
        A tuple of alias tuples.

    """
    from optimade.server.config import CONFIG

    return (
        tuple(
            (f"_{CONFIG.provider.prefix}_{field}", field)
            if not field.startswith("_")
            else (field, field)
            for field in CONFIG.provider_fields.get(cls.ENDPOINT, [])
            if isinstance(field, str)
        )
        + tuple(
            (f"_{CONFIG.provider.prefix}_{field['name']}", field["name"])
            if not field["name"].startswith("_")
            else (field["name"], field["name"])
            for field in CONFIG.provider_fields.get(cls.ENDPOINT, [])
            if isinstance(field, dict)
        )
        + tuple(
            (f"_{CONFIG.provider.prefix}_{field}", field)
            if not field.startswith("_")
            else (field, field)
            for field in cls.PROVIDER_FIELDS
        )
        + tuple(CONFIG.aliases.get(cls.ENDPOINT, {}).items())
        + cls.ALIASES
    )

all_length_aliases() cached classmethod

Returns all of the associated length aliases for this class, including those defined by the server config.

Returns:

Type Description
tuple[tuple[str, str], ...]

A tuple of length alias tuples.
Source code in optimade/server/mappers/entries.py 
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
@classmethod
@lru_cache(maxsize=NUM_ENTRY_TYPES)
def all_length_aliases(cls) -> tuple[tuple[str, str], ...]:
    """Returns all of the associated length aliases for this class,
    including those defined by the server config.

    Returns:
        A tuple of length alias tuples.

    """
    from optimade.server.config import CONFIG

    return cls.LENGTH_ALIASES + tuple(
        CONFIG.length_aliases.get(cls.ENDPOINT, {}).items()
    )

deserialize(results) classmethod

Converts the raw database entries for this class into serialized models, mapping the data along the way.

Source code in optimade/server/mappers/entries.py 
367
368
369
370
371
372
373
374
375
376
377
378
@classmethod
def deserialize(
    cls, results: Union[dict, Iterable[dict]]
) -> Union[list[EntryResource], EntryResource]:
    """Converts the raw database entries for this class into serialized models,
    mapping the data along the way.

    """
    if isinstance(results, dict):
        return cls.ENTRY_RESOURCE_CLASS(**cls.map_back(results))

    return [cls.ENTRY_RESOURCE_CLASS(**cls.map_back(doc)) for doc in results]

get_backend_field(optimade_field) cached classmethod

Return the field name configured for the particular underlying database for the passed OPTIMADE field name, that would be used in an API filter.

Aliases are read from all_aliases().

If a dot-separated OPTIMADE field is provided, e.g., species.mass, only the first part will be mapped. This means for an (OPTIMADE, DB) alias of (species, kinds), get_backend_fields("species.mass") will return kinds.mass.

Parameters:

Name Type Description Default
optimade_field str

The OPTIMADE field to attempt to map to the backend-specific field.

 required

Examples:

>>> get_backend_field("chemical_formula_anonymous")
'formula_anon'
>>> get_backend_field("formula_anon")
'formula_anon'
>>> get_backend_field("_exmpl_custom_provider_field")
'custom_provider_field'

Returns:

Type Description
str

The mapped field name to be used in the query to the backend.
Source code in optimade/server/mappers/entries.py 
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
@classmethod
@lru_cache(maxsize=128)
def get_backend_field(cls, optimade_field: str) -> str:
    """Return the field name configured for the particular
    underlying database for the passed OPTIMADE field name, that would
    be used in an API filter.

    Aliases are read from
    [`all_aliases()`][optimade.server.mappers.entries.BaseResourceMapper.all_aliases].

    If a dot-separated OPTIMADE field is provided, e.g., `species.mass`, only the first part will be mapped.
    This means for an (OPTIMADE, DB) alias of (`species`, `kinds`), `get_backend_fields("species.mass")`
    will return `kinds.mass`.

    Arguments:
        optimade_field: The OPTIMADE field to attempt to map to the backend-specific field.

    Examples:
        >>> get_backend_field("chemical_formula_anonymous")
        'formula_anon'
        >>> get_backend_field("formula_anon")
        'formula_anon'
        >>> get_backend_field("_exmpl_custom_provider_field")
        'custom_provider_field'

    Returns:
        The mapped field name to be used in the query to the backend.

    """
    split = optimade_field.split(".")
    alias = dict(cls.all_aliases()).get(split[0], None)
    if alias is not None:
        return alias + ("." + ".".join(split[1:]) if len(split) > 1 else "")
    return optimade_field

get_optimade_field(backend_field) cached classmethod

Return the corresponding OPTIMADE field name for the underlying database field, ready to be used to construct the OPTIMADE-compliant JSON response.

Aliases are read from all_aliases().

Parameters:

Name Type Description Default
backend_field str

The backend field to attempt to map to an OPTIMADE field.

 required

Examples:

>>> get_optimade_field("chemical_formula_anonymous")
'chemical_formula_anonymous'
>>> get_optimade_field("formula_anon")
'chemical_formula_anonymous'
>>> get_optimade_field("custom_provider_field")
'_exmpl_custom_provider_field'

Returns:

Type Description
str

The mapped field name to be used in an OPTIMADE-compliant response.
Source code in optimade/server/mappers/entries.py 
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
@classmethod
@lru_cache(maxsize=128)
def get_optimade_field(cls, backend_field: str) -> str:
    """Return the corresponding OPTIMADE field name for the underlying database field,
    ready to be used to construct the OPTIMADE-compliant JSON response.

    Aliases are read from
    [`all_aliases()`][optimade.server.mappers.entries.BaseResourceMapper.all_aliases].

    Arguments:
        backend_field: The backend field to attempt to map to an OPTIMADE field.

    Examples:
        >>> get_optimade_field("chemical_formula_anonymous")
        'chemical_formula_anonymous'
        >>> get_optimade_field("formula_anon")
        'chemical_formula_anonymous'
        >>> get_optimade_field("custom_provider_field")
        '_exmpl_custom_provider_field'

    Returns:
        The mapped field name to be used in an OPTIMADE-compliant response.

    """
    return {alias: real for real, alias in cls.all_aliases()}.get(
        backend_field, backend_field
    )

get_required_fields() cached classmethod

Get REQUIRED response fields.

Returns:

Type Description
set

REQUIRED response fields.
Source code in optimade/server/mappers/entries.py 
312
313
314
315
316
317
318
319
320
321
@classmethod
@lru_cache(maxsize=NUM_ENTRY_TYPES)
def get_required_fields(cls) -> set:
    """Get REQUIRED response fields.

    Returns:
        REQUIRED response fields.

    """
    return cls.TOP_LEVEL_NON_ATTRIBUTES_FIELDS

length_alias_for(field) cached classmethod

Returns the length alias for the particular field, or None if no such alias is found.

Parameters:

Name Type Description Default
field str

OPTIMADE field name.

 required

Returns:

Type Description
Optional[str]

Aliased field as found in all_length_aliases().
Source code in optimade/server/mappers/entries.py 
189
190
191
192
193
194
195
196
197
198
199
200
201
202
@classmethod
@lru_cache(maxsize=128)
def length_alias_for(cls, field: str) -> Optional[str]:
    """Returns the length alias for the particular field,
    or `None` if no such alias is found.

    Parameters:
        field: OPTIMADE field name.

    Returns:
        Aliased field as found in [`all_length_aliases()`][optimade.server.mappers.entries.BaseResourceMapper.all_length_aliases].

    """
    return dict(cls.all_length_aliases()).get(field, None)

map_back(doc) classmethod

Map properties from MongoDB to OPTIMADE.

Starting from a MongoDB document doc, map the DB fields to the corresponding OPTIMADE fields. Then, the fields are all added to the top-level field "attributes", with the exception of other top-level fields, defined in cls.TOP_LEVEL_NON_ATTRIBUTES_FIELDS. All fields not in cls.TOP_LEVEL_NON_ATTRIBUTES_FIELDS + "attributes" will be removed. Finally, the type is given the value of the specified cls.ENDPOINT.

Parameters:

Name Type Description Default
doc dict

A resource object in MongoDB format.

 required

Returns:

Type Description
dict

A resource object in OPTIMADE format.
Source code in optimade/server/mappers/entries.py 
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
@classmethod
def map_back(cls, doc: dict) -> dict:
    """Map properties from MongoDB to OPTIMADE.

    Starting from a MongoDB document `doc`, map the DB fields to the corresponding OPTIMADE fields.
    Then, the fields are all added to the top-level field "attributes",
    with the exception of other top-level fields, defined in `cls.TOP_LEVEL_NON_ATTRIBUTES_FIELDS`.
    All fields not in `cls.TOP_LEVEL_NON_ATTRIBUTES_FIELDS` + "attributes" will be removed.
    Finally, the `type` is given the value of the specified `cls.ENDPOINT`.

    Parameters:
        doc: A resource object in MongoDB format.

    Returns:
        A resource object in OPTIMADE format.

    """
    mapping = ((real, alias) for alias, real in cls.all_aliases())
    newdoc = {}
    reals = {real for _, real in cls.all_aliases()}
    for key in doc:
        if key not in reals:
            newdoc[key] = doc[key]
    for real, alias in mapping:
        if real in doc:
            newdoc[alias] = doc[real]

    if "attributes" in newdoc:
        raise Exception("Will overwrite doc field!")
    attributes = newdoc.copy()

    for field in cls.TOP_LEVEL_NON_ATTRIBUTES_FIELDS:
        value = attributes.pop(field, None)
        if value is not None:
            newdoc[field] = value
    for field in list(newdoc.keys()):
        if field not in cls.TOP_LEVEL_NON_ATTRIBUTES_FIELDS:
            del newdoc[field]

    newdoc["type"] = cls.ENDPOINT
    newdoc["attributes"] = attributes

    return newdoc

BaseTransformer

Bases: Transformer, ABC

Generic filter transformer that handles various parts of the grammar in a backend non-specific way.

Attributes:

Name Type Description
operator_map dict[str, Optional[str]]

A map from comparison operators to their backend-specific versions.
mapper Optional[type[BaseResourceMapper]]

A resource mapper object that defines the expected fields and acts as a container for various field-related configuration.
Source code in optimade/filtertransformers/base_transformer.py 
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
class BaseTransformer(Transformer, abc.ABC):
    """Generic filter transformer that handles various
    parts of the grammar in a backend non-specific way.

    Attributes:
        operator_map: A map from comparison operators
            to their backend-specific versions.
        mapper: A resource mapper object that defines the
            expected fields and acts as a container for
            various field-related configuration.

    """

    mapper: Optional[type[BaseResourceMapper]] = None
    operator_map: dict[str, Optional[str]] = {
        "<": None,
        "<=": None,
        ">": None,
        ">=": None,
        "!=": None,
        "=": None,
    }

    # map from operators to their syntactic (as opposed to logical) inverse to handle
    # equivalence between cases like "A > 3" and "3 < A".
    _reversed_operator_map = {
        ">": "<",
        ">=": "<=",
        "<": ">",
        "<=": ">=",
        "=": "=",
        "!=": "!=",
    }

    _quantity_type: type[Quantity] = Quantity
    _quantities = None

    def __init__(
        self, mapper: Optional[type[BaseResourceMapper]] = None
    ):  # pylint: disable=super-init-not-called
        """Initialise the transformer object, optionally loading in a
        resource mapper for use when post-processing.

        """
        self.mapper = mapper

    @property
    def backend_mapping(self) -> dict[str, Quantity]:
        """A mapping between backend field names (aliases) and the corresponding
        [`Quantity`][optimade.filtertransformers.base_transformer.Quantity] object.
        """
        return {
            quantity.backend_field: quantity for _, quantity in self.quantities.items()  # type: ignore[misc]
        }

    @property
    def quantities(self) -> dict[str, Quantity]:
        """A mapping from the OPTIMADE field name to the corresponding
        [`Quantity`][optimade.filtertransformers.base_transformer.Quantity] objects.
        """
        if self._quantities is None:
            self._quantities = self._build_quantities()

        return self._quantities

    @quantities.setter
    def quantities(self, quantities: dict[str, Quantity]) -> None:
        self._quantities = quantities

    def _build_quantities(self) -> dict[str, Quantity]:
        """Creates a dictionary of field names mapped to
        [`Quantity`][optimade.filtertransformers.base_transformer.Quantity] objects from the
        fields registered by the mapper.

        """

        quantities = {}

        if self.mapper is not None:
            for field in self.mapper.ALL_ATTRIBUTES:
                alias = self.mapper.get_backend_field(field)
                # Allow length aliases to be defined relative to either backend fields or OPTIMADE fields,
                # with preference for those defined from OPTIMADE fields
                length_alias = self.mapper.length_alias_for(
                    field
                ) or self.mapper.length_alias_for(alias)

                if field not in quantities:
                    quantities[field] = self._quantity_type(
                        name=field, backend_field=alias
                    )

                if length_alias:
                    if length_alias not in quantities:
                        quantities[length_alias] = self._quantity_type(
                            name=length_alias,
                            backend_field=self.mapper.get_backend_field(length_alias),
                        )
                    quantities[field].length_quantity = quantities[length_alias]

        return quantities

    def postprocess(self, query) -> Any:
        """Post-process the query according to the rules defined for
        the backend, returning the backend-specific query.

        """
        return query

    def transform(self, tree: Tree) -> Any:
        """Transform the query using the Lark `Transformer` then run the
        backend-specific post-processing methods.

        """
        return self.postprocess(super().transform(tree))

    def __default__(self, data, children, meta):
        """The default rule to call when no definition is found for a particular construct."""
        raise NotImplementedError(
            f"Calling __default__, i.e., unknown grammar concept. data: {data}, children: {children}, meta: {meta}"
        )

    def filter(self, arg):
        """filter: expression*"""
        return arg[0] if arg else None

    @v_args(inline=True)
    def constant(self, value):
        """constant: string | number"""
        # Note: Return as is.
        return value

    @v_args(inline=True)
    def value(self, value):
        """value: string | number | property"""
        # Note: Return as is.
        return value

    @v_args(inline=True)
    def non_string_value(self, value):
        """non_string_value: number | property"""
        # Note: Return as is.
        return value

    @v_args(inline=True)
    def not_implemented_string(self, value):
        """not_implemented_string: value

        Raises:
            NotImplementedError: For further information, see Materials-Consortia/OPTIMADE issue 157:
                https://github.com/Materials-Consortia/OPTIMADE/issues/157

        """
        raise NotImplementedError("Comparing strings is not yet implemented.")

    def property(self, args: list) -> Any:
        """property: IDENTIFIER ( "." IDENTIFIER )*

        If this transformer has an associated mapper, the property
        will be compared to possible relationship entry types and
        for any supported provider prefixes. If there is a match,
        this rule will return a string and not a dereferenced
        [`Quantity`][optimade.filtertransformers.base_transformer.Quantity].

        Raises:
            BadRequest: If the property does not match any
                of the above rules.

        """
        quantity_name = str(args[0])

        # If the quantity name matches an entry type (indicating a relationship filter)
        # then simply return the quantity name; the inherited property
        # must then handle any further nested identifiers
        if self.mapper:
            if quantity_name in self.mapper.RELATIONSHIP_ENTRY_TYPES:
                return quantity_name

        if self.quantities and quantity_name not in self.quantities:
            # If the quantity is provider-specific, but does not match this provider,
            # then return the quantity name such that it can be treated as unknown.
            # If the prefix does not match another known provider, also emit a warning
            # If the prefix does match a known provider, do not return a warning.
            # Following [Handling unknown property names](https://github.com/Materials-Consortia/OPTIMADE/blob/master/optimade.rst#handling-unknown-property-names)
            if self.mapper and quantity_name.startswith("_"):
                prefix = quantity_name.split("_")[1]
                if prefix not in self.mapper.SUPPORTED_PREFIXES:
                    if prefix not in self.mapper.KNOWN_PROVIDER_PREFIXES:
                        warnings.warn(
                            UnknownProviderProperty(
                                f"Field {quantity_name!r} has an unrecognised prefix: this property has been treated as UNKNOWN."
                            )
                        )

                    return quantity_name

            raise BadRequest(
                detail=f"'{quantity_name}' is not a known or searchable quantity"
            )

        quantity = self.quantities.get(quantity_name, None)
        if quantity is None:
            quantity = self._quantity_type(name=str(quantity_name))

        return quantity

    @v_args(inline=True)
    def string(self, string):
        """string: ESCAPED_STRING"""
        return string.strip('"')

    @v_args(inline=True)
    def signed_int(self, number):
        """signed_int : SIGNED_INT"""
        return int(number)

    @v_args(inline=True)
    def number(self, number):
        """number: SIGNED_INT | SIGNED_FLOAT"""
        if TYPE_CHECKING:  # pragma: no cover
            type_: Union[type[int], type[float]]

        if number.type == "SIGNED_INT":
            type_ = int
        elif number.type == "SIGNED_FLOAT":
            type_ = float
        return type_(number)

    @v_args(inline=True)
    def comparison(self, value):
        """comparison: constant_first_comparison | property_first_comparison"""
        # Note: Return as is.
        return value

    def value_list(self, arg):
        """value_list: [ OPERATOR ] value ( "," [ OPERATOR ] value )*"""

    def value_zip(self, arg):
        """value_zip: [ OPERATOR ] value ":" [ OPERATOR ] value (":" [ OPERATOR ] value)*"""
        pass

    def value_zip_list(self, arg):
        """value_zip_list: value_zip ( "," value_zip )*"""

    def expression(self, arg):
        """expression: expression_clause ( OR expression_clause )"""

    def expression_clause(self, arg):
        """expression_clause: expression_phrase ( AND expression_phrase )*"""

    def expression_phrase(self, arg):
        """expression_phrase: [ NOT ] ( comparison | "(" expression ")" )"""

    def property_first_comparison(self, arg):
        """property_first_comparison:
        property ( value_op_rhs
                 | known_op_rhs
                 | fuzzy_string_op_rhs
                 | set_op_rhs
                 | set_zip_op_rhs
                 | length_op_rhs )

        """

    def constant_first_comparison(self, arg):
        """constant_first_comparison: constant OPERATOR ( non_string_value | not_implemented_string )"""

    @v_args(inline=True)
    def value_op_rhs(self, operator, value):
        """value_op_rhs: OPERATOR value"""

    def known_op_rhs(self, arg):
        """known_op_rhs: IS ( KNOWN | UNKNOWN )"""

    def fuzzy_string_op_rhs(self, arg):
        """fuzzy_string_op_rhs: CONTAINS value | STARTS [ WITH ] value | ENDS [ WITH ] value"""

    def set_op_rhs(self, arg):
        """set_op_rhs: HAS ( [ OPERATOR ] value | ALL value_list | ANY value_list | ONLY value_list )"""

    def length_op_rhs(self, arg):
        """length_op_rhs: LENGTH [ OPERATOR ] value"""

    def set_zip_op_rhs(self, arg):
        """set_zip_op_rhs: property_zip_addon HAS ( value_zip
        | ONLY value_zip_list
        | ALL value_zip_list
        | ANY value_zip_list )

        """

    def property_zip_addon(self, arg):
        """property_zip_addon: ":" property (":" property)*"""

backend_mapping: dict[str, Quantity] property

A mapping between backend field names (aliases) and the corresponding Quantity object.

quantities: dict[str, Quantity] property writable

A mapping from the OPTIMADE field name to the corresponding Quantity objects.

__default__(data, children, meta)

The default rule to call when no definition is found for a particular construct.

Source code in optimade/filtertransformers/base_transformer.py 
188
189
190
191
192
def __default__(self, data, children, meta):
    """The default rule to call when no definition is found for a particular construct."""
    raise NotImplementedError(
        f"Calling __default__, i.e., unknown grammar concept. data: {data}, children: {children}, meta: {meta}"
    )

__init__(mapper=None)

Initialise the transformer object, optionally loading in a resource mapper for use when post-processing.

Source code in optimade/filtertransformers/base_transformer.py 
109
110
111
112
113
114
115
116
def __init__(
    self, mapper: Optional[type[BaseResourceMapper]] = None
):  # pylint: disable=super-init-not-called
    """Initialise the transformer object, optionally loading in a
    resource mapper for use when post-processing.

    """
    self.mapper = mapper

comparison(value)

comparison: constant_first_comparison | property_first_comparison

Source code in optimade/filtertransformers/base_transformer.py 
300
301
302
303
304
@v_args(inline=True)
def comparison(self, value):
    """comparison: constant_first_comparison | property_first_comparison"""
    # Note: Return as is.
    return value

constant(value)

constant: string | number

Source code in optimade/filtertransformers/base_transformer.py 
198
199
200
201
202
@v_args(inline=True)
def constant(self, value):
    """constant: string | number"""
    # Note: Return as is.
    return value

constant_first_comparison(arg)

constant_first_comparison: constant OPERATOR ( non_string_value | not_implemented_string )

Source code in optimade/filtertransformers/base_transformer.py 
336
337
def constant_first_comparison(self, arg):
    """constant_first_comparison: constant OPERATOR ( non_string_value | not_implemented_string )"""

expression(arg)

expression: expression_clause ( OR expression_clause )

Source code in optimade/filtertransformers/base_transformer.py 
316
317
def expression(self, arg):
    """expression: expression_clause ( OR expression_clause )"""

expression_clause(arg)

expression_clause: expression_phrase ( AND expression_phrase )*

Source code in optimade/filtertransformers/base_transformer.py 
319
320
def expression_clause(self, arg):
    """expression_clause: expression_phrase ( AND expression_phrase )*"""

expression_phrase(arg)

expression_phrase: [ NOT ] ( comparison | "(" expression ")" )

Source code in optimade/filtertransformers/base_transformer.py 
322
323
def expression_phrase(self, arg):
    """expression_phrase: [ NOT ] ( comparison | "(" expression ")" )"""

filter(arg)

filter: expression*

Source code in optimade/filtertransformers/base_transformer.py 
194
195
196
def filter(self, arg):
    """filter: expression*"""
    return arg[0] if arg else None

fuzzy_string_op_rhs(arg)

fuzzy_string_op_rhs: CONTAINS value | STARTS [ WITH ] value | ENDS [ WITH ] value

Source code in optimade/filtertransformers/base_transformer.py 
346
347
def fuzzy_string_op_rhs(self, arg):
    """fuzzy_string_op_rhs: CONTAINS value | STARTS [ WITH ] value | ENDS [ WITH ] value"""

known_op_rhs(arg)

known_op_rhs: IS ( KNOWN | UNKNOWN )

Source code in optimade/filtertransformers/base_transformer.py 
343
344
def known_op_rhs(self, arg):
    """known_op_rhs: IS ( KNOWN | UNKNOWN )"""

length_op_rhs(arg)

length_op_rhs: LENGTH [ OPERATOR ] value

Source code in optimade/filtertransformers/base_transformer.py 
352
353
def length_op_rhs(self, arg):
    """length_op_rhs: LENGTH [ OPERATOR ] value"""

non_string_value(value)

non_string_value: number | property

Source code in optimade/filtertransformers/base_transformer.py 
210
211
212
213
214
@v_args(inline=True)
def non_string_value(self, value):
    """non_string_value: number | property"""
    # Note: Return as is.
    return value

not_implemented_string(value)

not_implemented_string: value

Raises:

Type Description
NotImplementedError

For further information, see Materials-Consortia/OPTIMADE issue 157: https://github.com/Materials-Consortia/OPTIMADE/issues/157
Source code in optimade/filtertransformers/base_transformer.py 
216
217
218
219
220
221
222
223
224
225
@v_args(inline=True)
def not_implemented_string(self, value):
    """not_implemented_string: value

    Raises:
        NotImplementedError: For further information, see Materials-Consortia/OPTIMADE issue 157:
            https://github.com/Materials-Consortia/OPTIMADE/issues/157

    """
    raise NotImplementedError("Comparing strings is not yet implemented.")

number(number)

number: SIGNED_INT | SIGNED_FLOAT

Source code in optimade/filtertransformers/base_transformer.py 
288
289
290
291
292
293
294
295
296
297
298
@v_args(inline=True)
def number(self, number):
    """number: SIGNED_INT | SIGNED_FLOAT"""
    if TYPE_CHECKING:  # pragma: no cover
        type_: Union[type[int], type[float]]

    if number.type == "SIGNED_INT":
        type_ = int
    elif number.type == "SIGNED_FLOAT":
        type_ = float
    return type_(number)

postprocess(query)

Post-process the query according to the rules defined for the backend, returning the backend-specific query.

Source code in optimade/filtertransformers/base_transformer.py 
174
175
176
177
178
179
def postprocess(self, query) -> Any:
    """Post-process the query according to the rules defined for
    the backend, returning the backend-specific query.

    """
    return query

property(args)

property: IDENTIFIER ( "." IDENTIFIER )*

If this transformer has an associated mapper, the property will be compared to possible relationship entry types and for any supported provider prefixes. If there is a match, this rule will return a string and not a dereferenced Quantity.

Raises:

Type Description
BadRequest

If the property does not match any of the above rules.
Source code in optimade/filtertransformers/base_transformer.py 
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
def property(self, args: list) -> Any:
    """property: IDENTIFIER ( "." IDENTIFIER )*

    If this transformer has an associated mapper, the property
    will be compared to possible relationship entry types and
    for any supported provider prefixes. If there is a match,
    this rule will return a string and not a dereferenced
    [`Quantity`][optimade.filtertransformers.base_transformer.Quantity].

    Raises:
        BadRequest: If the property does not match any
            of the above rules.

    """
    quantity_name = str(args[0])

    # If the quantity name matches an entry type (indicating a relationship filter)
    # then simply return the quantity name; the inherited property
    # must then handle any further nested identifiers
    if self.mapper:
        if quantity_name in self.mapper.RELATIONSHIP_ENTRY_TYPES:
            return quantity_name

    if self.quantities and quantity_name not in self.quantities:
        # If the quantity is provider-specific, but does not match this provider,
        # then return the quantity name such that it can be treated as unknown.
        # If the prefix does not match another known provider, also emit a warning
        # If the prefix does match a known provider, do not return a warning.
        # Following [Handling unknown property names](https://github.com/Materials-Consortia/OPTIMADE/blob/master/optimade.rst#handling-unknown-property-names)
        if self.mapper and quantity_name.startswith("_"):
            prefix = quantity_name.split("_")[1]
            if prefix not in self.mapper.SUPPORTED_PREFIXES:
                if prefix not in self.mapper.KNOWN_PROVIDER_PREFIXES:
                    warnings.warn(
                        UnknownProviderProperty(
                            f"Field {quantity_name!r} has an unrecognised prefix: this property has been treated as UNKNOWN."
                        )
                    )

                return quantity_name

        raise BadRequest(
            detail=f"'{quantity_name}' is not a known or searchable quantity"
        )

    quantity = self.quantities.get(quantity_name, None)
    if quantity is None:
        quantity = self._quantity_type(name=str(quantity_name))

    return quantity

property_first_comparison(arg)

property_first_comparison: property ( value_op_rhs | known_op_rhs | fuzzy_string_op_rhs | set_op_rhs | set_zip_op_rhs | length_op_rhs )

Source code in optimade/filtertransformers/base_transformer.py 
325
326
327
328
329
330
331
332
333
334
def property_first_comparison(self, arg):
    """property_first_comparison:
    property ( value_op_rhs
             | known_op_rhs
             | fuzzy_string_op_rhs
             | set_op_rhs
             | set_zip_op_rhs
             | length_op_rhs )

    """

property_zip_addon(arg)

property_zip_addon: ":" property (":" property)*

Source code in optimade/filtertransformers/base_transformer.py 
363
364
def property_zip_addon(self, arg):
    """property_zip_addon: ":" property (":" property)*"""

set_op_rhs(arg)

set_op_rhs: HAS ( [ OPERATOR ] value | ALL value_list | ANY value_list | ONLY value_list )

Source code in optimade/filtertransformers/base_transformer.py 
349
350
def set_op_rhs(self, arg):
    """set_op_rhs: HAS ( [ OPERATOR ] value | ALL value_list | ANY value_list | ONLY value_list )"""

set_zip_op_rhs(arg)

set_zip_op_rhs: property_zip_addon HAS ( value_zip | ONLY value_zip_list | ALL value_zip_list | ANY value_zip_list )

Source code in optimade/filtertransformers/base_transformer.py 
355
356
357
358
359
360
361
def set_zip_op_rhs(self, arg):
    """set_zip_op_rhs: property_zip_addon HAS ( value_zip
    | ONLY value_zip_list
    | ALL value_zip_list
    | ANY value_zip_list )

    """

signed_int(number)

signed_int : SIGNED_INT

Source code in optimade/filtertransformers/base_transformer.py 
283
284
285
286
@v_args(inline=True)
def signed_int(self, number):
    """signed_int : SIGNED_INT"""
    return int(number)

string(string)

string: ESCAPED_STRING

Source code in optimade/filtertransformers/base_transformer.py 
278
279
280
281
@v_args(inline=True)
def string(self, string):
    """string: ESCAPED_STRING"""
    return string.strip('"')

transform(tree)

Transform the query using the Lark Transformer then run the backend-specific post-processing methods.

Source code in optimade/filtertransformers/base_transformer.py 
181
182
183
184
185
186
def transform(self, tree: Tree) -> Any:
    """Transform the query using the Lark `Transformer` then run the
    backend-specific post-processing methods.

    """
    return self.postprocess(super().transform(tree))

value(value)

value: string | number | property

Source code in optimade/filtertransformers/base_transformer.py 
204
205
206
207
208
@v_args(inline=True)
def value(self, value):
    """value: string | number | property"""
    # Note: Return as is.
    return value

value_list(arg)

value_list: [ OPERATOR ] value ( "," [ OPERATOR ] value )*

Source code in optimade/filtertransformers/base_transformer.py 
306
307
def value_list(self, arg):
    """value_list: [ OPERATOR ] value ( "," [ OPERATOR ] value )*"""

value_op_rhs(operator, value)

value_op_rhs: OPERATOR value

Source code in optimade/filtertransformers/base_transformer.py 
339
340
341
@v_args(inline=True)
def value_op_rhs(self, operator, value):
    """value_op_rhs: OPERATOR value"""

value_zip(arg)

value_zip: [ OPERATOR ] value ":" [ OPERATOR ] value (":" [ OPERATOR ] value)*

Source code in optimade/filtertransformers/base_transformer.py 
309
310
311
def value_zip(self, arg):
    """value_zip: [ OPERATOR ] value ":" [ OPERATOR ] value (":" [ OPERATOR ] value)*"""
    pass

value_zip_list(arg)

value_zip_list: value_zip ( "," value_zip )*

Source code in optimade/filtertransformers/base_transformer.py 
313
314
def value_zip_list(self, arg):
    """value_zip_list: value_zip ( "," value_zip )*"""

ElasticTransformer

Bases: BaseTransformer

Transformer that transforms v0.10.1/v1.0 grammar parse trees into Elasticsearch queries.

Uses elasticsearch_dsl and will produce an elasticsearch_dsl.Q instance.

Source code in optimade/filtertransformers/elasticsearch.py 
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
class ElasticTransformer(BaseTransformer):
    """Transformer that transforms ``v0.10.1``/`v1.0` grammar parse
    trees into Elasticsearch queries.

    Uses elasticsearch_dsl and will produce an `elasticsearch_dsl.Q` instance.

    """

    operator_map = {
        "<": "lt",
        "<=": "lte",
        ">": "gt",
        ">=": "gte",
    }

    _quantity_type: type[ElasticsearchQuantity] = ElasticsearchQuantity

    def __init__(
        self,
        mapper: type[BaseResourceMapper],
        quantities: Optional[dict[str, Quantity]] = None,
    ):
        if quantities is not None:
            self.quantities = quantities

        super().__init__(mapper=mapper)

    def _field(
        self, quantity: Union[str, Quantity], nested: Optional[Quantity] = None
    ) -> str:
        """Used to unwrap from `property` to the string backend field name.

        If passed a `Quantity` (or a derived `ElasticsearchQuantity`), this method
        returns the backend field name, modulo some handling of nested fields.

        If passed a string quantity name:
        - Check that the name does not match a relationship type,
          raising a `NotImplementedError` if it does.
        - If the string is prefixed by an underscore, assume this is a
          provider-specific field from another provider and simply return it.
          The original `property` rule would have already filtered out provider
          fields for this backend appropriately as `Quantity` objects.

        Returns:
            The field name to use for database queries.

        """

        if isinstance(quantity, str):
            if quantity in self.mapper.RELATIONSHIP_ENTRY_TYPES:  # type: ignore[union-attr]
                raise NotImplementedError(
                    f"Unable to filter on relationships with type {quantity!r}"
                )

            # In this case, the property rule has already filtered out fields
            # that do not match this provider, so this indicates an "other provider"
            # field that should be passed over
            if quantity.startswith("_"):
                return quantity

        if nested is not None:
            return f"{nested.backend_field}.{quantity.name}"  # type: ignore[union-attr]

        return quantity.backend_field  # type: ignore[union-attr, return-value]

    def _query_op(
        self,
        quantity: Union[ElasticsearchQuantity, str],
        op: str,
        value: Union[str, float, int],
        nested: Optional[ElasticsearchQuantity] = None,
    ) -> Q:
        """Return a range, match, or term query for the given quantity, comparison
        operator, and value.

        Returns:
            An elasticsearch_dsl query.

        Raises:
            BadRequest: If the query is not well-defined or is not supported.
        """
        field = self._field(quantity, nested=nested)
        if op in self.operator_map:
            return Q("range", **{field: {self.operator_map[op]: value}})

        # If quantity is an "other provider" field then use Keyword as the default
        # mapping type. These queries should not match on anything as the field
        # is not present in the index.
        elastic_mapping_type = Keyword
        if isinstance(quantity, ElasticsearchQuantity):
            elastic_mapping_type = quantity.elastic_mapping_type

        if elastic_mapping_type == Text:
            query_type = "match"
        elif elastic_mapping_type in [Keyword, Integer]:
            query_type = "term"
        else:
            raise NotImplementedError("Quantity has unsupported ES field type")

        if op in ["=", ""]:
            return Q(query_type, **{field: value})

        if op == "!=":
            # != queries must also include an existence check
            # Note that for MongoDB, `$exists` will include null-valued fields,
            # where as in ES `exists` excludes them.
            # pylint: disable=invalid-unary-operand-type
            return ~Q(query_type, **{field: value}) & Q("exists", field=field)

    def _has_query_op(self, quantities, op, predicate_zip_list):
        """Returns a bool query that combines the operator calls `_query_op`
        for each predicate and zipped quantity predicate combination.
        """
        if op == "HAS":
            kind = "must"  # in case of HAS we do a must over the "list" of the one given element
        elif op == "HAS ALL":
            kind = "must"
        elif op == "HAS ANY":
            kind = "should"
        elif op == "HAS ONLY":
            # HAS ONLY comes with heavy limitations, because there is no such thing
            # in elastic search. Only supported for elements, where we can construct
            # an anonymous "formula" based on elements sorted by order number and
            # can do a = comparision to check if all elements are contained

            # @ml-evs: Disabling this HAS ONLY workaround as tests are not passing
            raise NotImplementedError(
                "HAS ONLY queries are not currently supported by the Elasticsearch backend."
            )

            # from optimade.models import CHEMICAL_SYMBOLS, ATOMIC_NUMBERS

            # if len(quantities) > 1:
            #     raise NotImplementedError("HAS ONLY is not supported with zip")
            # quantity = quantities[0]

            # if quantity.has_only_quantity is None:
            #     raise NotImplementedError(
            #         "HAS ONLY is not supported by %s" % quantity.name
            #     )

            # def values():
            #     for predicates in predicate_zip_list:
            #         if len(predicates) != 1:
            #             raise NotImplementedError("Tuples not supported in HAS ONLY")
            #         op, value = predicates[0]
            #         if op != "=":
            #             raise NotImplementedError(
            #                 "Predicated not supported in HAS ONLY"
            #             )
            #         if not isinstance(value, str):
            #             raise NotImplementedError("Only strings supported in HAS ONLY")
            #         yield value

            # try:
            #     order_numbers = list([ATOMIC_NUMBERS[element] for element in values()])
            #     order_numbers.sort()
            #     value = "".join(
            #         [CHEMICAL_SYMBOLS[number - 1] for number in order_numbers]
            #     )
            # except KeyError:
            #     raise NotImplementedError(
            #         "HAS ONLY is only supported for chemical symbols"
            #     )

            # return Q("term", **{quantity.has_only_quantity.name: value})
        else:
            raise NotImplementedError(f"Unrecognised operation {op}.")

        queries = [
            self._has_query(quantities, predicates) for predicates in predicate_zip_list
        ]
        return Q("bool", **{kind: queries})

    def _has_query(self, quantities, predicates):
        """
        Returns a bool query that combines the operator queries ():func:`_query_op`)
        for quantity pericate combination.
        """
        if len(quantities) != len(predicates):
            raise ValueError(
                "Tuple length does not match: %s <o> %s "
                % (":".join(quantities), ":".join(predicates))
            )

        if len(quantities) == 1:
            o, value = predicates[0]
            return self._query_op(quantities[0], o, value)

        nested_quantity = quantities[0].nested_quantity
        same_nested_quantity = any(
            q.nested_quantity != nested_quantity for q in quantities
        )
        if nested_quantity is None or same_nested_quantity:
            raise NotImplementedError(
                "Expression with tuples are only supported for %s"
                % ", ".join(quantities)
            )

        queries = [
            self._query_op(quantity, o, value, nested=nested_quantity)
            for quantity, (o, value) in zip(quantities, predicates)
        ]

        return Q(
            "nested",
            path=self._field(nested_quantity),
            query=dict(bool=dict(must=queries)),
        )

    def __default__(self, tree, children, *args, **kwargs):
        """Default behavior for rules that only replace one symbol with another"""
        return children[0]

    def filter(self, args):
        # filter: expression*
        if len(args) == 1:
            return args[0]
        return Q("bool", **{"must": args})

    def expression_clause(self, args):
        # expression_clause: expression_phrase ( _AND expression_phrase )*
        result = args[0]
        for arg in args[1:]:
            result &= arg
        return result

    def expression(self, args):
        # expression: expression_clause ( _OR expression_clause )*
        result = args[0]
        for arg in args[1:]:
            result |= arg
        return result

    def expression_phrase(self, args):
        # expression_phrase: [ NOT ] ( operator | "(" expression ")" )
        if args[0] == "NOT":
            return ~args[1]
        return args[0]

    @v_args(inline=True)
    def property_first_comparison(self, quantity, query):
        # property_first_comparison: property *_rhs
        return query(quantity)

    @v_args(inline=True)
    def constant_first_comparison(self, value, op, quantity):
        # constant_first_comparison: constant OPERATOR ( non_string_value | ...not_implemented_string )
        if not isinstance(quantity, ElasticsearchQuantity):
            raise TypeError("Only quantities can be compared to constant values.")

        return self._query_op(quantity, self._reversed_operator_map[op], value)

    @v_args(inline=True)
    def value_op_rhs(self, op, value):
        # value_op_rhs: OPERATOR value
        return lambda quantity: self._query_op(quantity, op, value)

    def length_op_rhs(self, args):
        # length_op_rhs: LENGTH [ OPERATOR ] signed_int
        value = args[-1]
        if len(args) == 3:
            op = args[1]
        else:
            op = "="

        def query(quantity):
            # This is only the case if quantity is an "other" provider's field,
            # in which case, we should treat it as unknown and try to do a null query
            if isinstance(quantity, str):
                return self._query_op(quantity, op, value)

            if quantity.length_quantity is None:
                raise NotImplementedError(
                    f"LENGTH is not supported for {quantity.name!r}"
                )
            quantity = quantity.length_quantity
            return self._query_op(quantity, op, value)

        return query

    @v_args(inline=True)
    def known_op_rhs(self, _, value):
        # known_op_rhs: IS ( KNOWN | UNKNOWN )

        def query(quantity):
            query = Q("exists", field=self._field(quantity))
            if value == "KNOWN":
                return query
            elif value == "UNKNOWN":
                return ~query  # pylint: disable=invalid-unary-operand-type
            raise NotImplementedError

        return query

    def set_op_rhs(self, args):
        # set_op_rhs: HAS ( [ OPERATOR ] value | ALL value_list | ... )
        values = args[-1]
        if not isinstance(values, list):
            if len(args) == 3:
                op = args[1]
            else:
                op = "="
            values = [(op, values)]

        if len(args) == 3:
            op = "HAS " + args[1]
        else:
            op = "HAS"

        return lambda quantity: self._has_query_op(
            [quantity], op, [[value] for value in values]
        )

    def set_zip_op_rhs(self, args):
        # set_zip_op_rhs: property_zip_addon HAS ( value_zip | ONLY value_zip_list | ALL value_zip_list | ANY value_zip_list )
        add_on = args[0]
        values = args[-1]
        if len(args) == 4:
            op = "HAS " + args[2]
        else:
            op = "HAS"
            values = [values]

        return lambda quantity: self._has_query_op([quantity] + add_on, op, values)

    def property_zip_addon(self, args):
        raise NotImplementedError("Correlated list queries are not supported.")
        return args

    def value_zip(self, args):
        raise NotImplementedError("Correlated list queries are not supported.")
        return self.value_list(args)

    def value_zip_list(self, args):
        raise NotImplementedError("Correlated list queries are not supported.")
        return args

    def value_list(self, args):
        result = []
        op = "="
        for arg in args:
            if arg in ["<", "<=", ">", ">=", "!=", "="]:
                op = arg
            else:
                result.append(
                    (
                        op,
                        arg,
                    )
                )
                op = "="
        return result

    def fuzzy_string_op_rhs(self, args):
        op = args[0]
        value = args[-1]
        if op == "CONTAINS":
            wildcard = "*%s*" % value
        if op == "STARTS":
            wildcard = "%s*" % value
        if op == "ENDS":
            wildcard = "*%s" % value

        return lambda quantity: Q("wildcard", **{self._field(quantity): wildcard})

    @v_args(inline=True)
    def string(self, string):
        # string: ESCAPED_STRING
        return string.strip('"')

    @v_args(inline=True)
    def signed_int(self, number):
        # signed_int : SIGNED_INT
        return int(number)

    @v_args(inline=True)
    def number(self, number):
        # number: SIGNED_INT | SIGNED_FLOAT
        if TYPE_CHECKING:  # pragma: no cover
            type_: Union[type[int], type[float]]

        if number.type == "SIGNED_INT":
            type_ = int
        elif number.type == "SIGNED_FLOAT":
            type_ = float
        return type_(number)

backend_mapping: dict[str, Quantity] property

A mapping between backend field names (aliases) and the corresponding Quantity object.

__default__(tree, children, *args, **kwargs)

Default behavior for rules that only replace one symbol with another

Source code in optimade/filtertransformers/elasticsearch.py 
295
296
297
def __default__(self, tree, children, *args, **kwargs):
    """Default behavior for rules that only replace one symbol with another"""
    return children[0]

comparison(value)

comparison: constant_first_comparison | property_first_comparison

Source code in optimade/filtertransformers/base_transformer.py 
300
301
302
303
304
@v_args(inline=True)
def comparison(self, value):
    """comparison: constant_first_comparison | property_first_comparison"""
    # Note: Return as is.
    return value

constant(value)

constant: string | number

Source code in optimade/filtertransformers/base_transformer.py 
198
199
200
201
202
@v_args(inline=True)
def constant(self, value):
    """constant: string | number"""
    # Note: Return as is.
    return value

non_string_value(value)

non_string_value: number | property

Source code in optimade/filtertransformers/base_transformer.py 
210
211
212
213
214
@v_args(inline=True)
def non_string_value(self, value):
    """non_string_value: number | property"""
    # Note: Return as is.
    return value

not_implemented_string(value)

not_implemented_string: value

Raises:

Type Description
NotImplementedError

For further information, see Materials-Consortia/OPTIMADE issue 157: https://github.com/Materials-Consortia/OPTIMADE/issues/157
Source code in optimade/filtertransformers/base_transformer.py 
216
217
218
219
220
221
222
223
224
225
@v_args(inline=True)
def not_implemented_string(self, value):
    """not_implemented_string: value

    Raises:
        NotImplementedError: For further information, see Materials-Consortia/OPTIMADE issue 157:
            https://github.com/Materials-Consortia/OPTIMADE/issues/157

    """
    raise NotImplementedError("Comparing strings is not yet implemented.")

postprocess(query)

Post-process the query according to the rules defined for the backend, returning the backend-specific query.

Source code in optimade/filtertransformers/base_transformer.py 
174
175
176
177
178
179
def postprocess(self, query) -> Any:
    """Post-process the query according to the rules defined for
    the backend, returning the backend-specific query.

    """
    return query

property(args)

property: IDENTIFIER ( "." IDENTIFIER )*

If this transformer has an associated mapper, the property will be compared to possible relationship entry types and for any supported provider prefixes. If there is a match, this rule will return a string and not a dereferenced Quantity.

Raises:

Type Description
BadRequest

If the property does not match any of the above rules.
Source code in optimade/filtertransformers/base_transformer.py 
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
def property(self, args: list) -> Any:
    """property: IDENTIFIER ( "." IDENTIFIER )*

    If this transformer has an associated mapper, the property
    will be compared to possible relationship entry types and
    for any supported provider prefixes. If there is a match,
    this rule will return a string and not a dereferenced
    [`Quantity`][optimade.filtertransformers.base_transformer.Quantity].

    Raises:
        BadRequest: If the property does not match any
            of the above rules.

    """
    quantity_name = str(args[0])

    # If the quantity name matches an entry type (indicating a relationship filter)
    # then simply return the quantity name; the inherited property
    # must then handle any further nested identifiers
    if self.mapper:
        if quantity_name in self.mapper.RELATIONSHIP_ENTRY_TYPES:
            return quantity_name

    if self.quantities and quantity_name not in self.quantities:
        # If the quantity is provider-specific, but does not match this provider,
        # then return the quantity name such that it can be treated as unknown.
        # If the prefix does not match another known provider, also emit a warning
        # If the prefix does match a known provider, do not return a warning.
        # Following [Handling unknown property names](https://github.com/Materials-Consortia/OPTIMADE/blob/master/optimade.rst#handling-unknown-property-names)
        if self.mapper and quantity_name.startswith("_"):
            prefix = quantity_name.split("_")[1]
            if prefix not in self.mapper.SUPPORTED_PREFIXES:
                if prefix not in self.mapper.KNOWN_PROVIDER_PREFIXES:
                    warnings.warn(
                        UnknownProviderProperty(
                            f"Field {quantity_name!r} has an unrecognised prefix: this property has been treated as UNKNOWN."
                        )
                    )

                return quantity_name

        raise BadRequest(
            detail=f"'{quantity_name}' is not a known or searchable quantity"
        )

    quantity = self.quantities.get(quantity_name, None)
    if quantity is None:
        quantity = self._quantity_type(name=str(quantity_name))

    return quantity

transform(tree)

Transform the query using the Lark Transformer then run the backend-specific post-processing methods.

Source code in optimade/filtertransformers/base_transformer.py 
181
182
183
184
185
186
def transform(self, tree: Tree) -> Any:
    """Transform the query using the Lark `Transformer` then run the
    backend-specific post-processing methods.

    """
    return self.postprocess(super().transform(tree))

value(value)

value: string | number | property

Source code in optimade/filtertransformers/base_transformer.py 
204
205
206
207
208
@v_args(inline=True)
def value(self, value):
    """value: string | number | property"""
    # Note: Return as is.
    return value

ElasticsearchQuantity

Bases: Quantity

Elasticsearch-specific extension of the underlying Quantity class.

Attributes:

Name Type Description
name str

The name of the quantity as used in the filter expressions.
backend_field Optional[str]

The name of the field for this quantity in Elasticsearch, will be name by default.
elastic_mapping_type Optional[Field]

A decendent of an elasticsearch_dsl.Field that denotes which mapping type was used in the Elasticsearch index.
length_quantity Optional[ElasticsearchQuantity]

Elasticsearch does not support length of arrays, but we can map fields with array to other fields with ints about the array length. The LENGTH operator will only be supported for quantities with this attribute.
has_only_quantity Optional[ElasticsearchQuantity]

Elasticsearch does not support exclusive search on arrays, like a list of chemical elements. But, we can order all elements by atomic number and use a keyword field with all elements to perform this search. This only works for elements (i.e. labels in CHEMICAL_SYMBOLS) and quantities with this attribute.
nested_quantity Optional[ElasticsearchQuantity]

To support optimade's 'zipped tuple' feature (e.g. 'elements:elements_ratios HAS "H":>0.33), we use elasticsearch nested objects and nested queries. This quantity will provide the field for the nested object that contains the quantity (and others). The zipped tuples will only work for quantities that share the same nested object quantity.
Source code in optimade/filtertransformers/elasticsearch.py 
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
class ElasticsearchQuantity(Quantity):
    """Elasticsearch-specific extension of the underlying
    [`Quantity`][optimade.filtertransformers.base_transformer.Quantity] class.

    Attributes:
        name: The name of the quantity as used in the filter expressions.
        backend_field: The name of the field for this quantity in Elasticsearch, will be
            ``name`` by default.
        elastic_mapping_type: A decendent of an `elasticsearch_dsl.Field` that denotes which
            mapping type was used in the Elasticsearch index.
        length_quantity: Elasticsearch does not support length of arrays, but we can
            map fields with array to other fields with ints about the array length. The
            LENGTH operator will only be supported for quantities with this attribute.
        has_only_quantity: Elasticsearch does not support exclusive search on arrays, like
            a list of chemical elements. But, we can order all elements by atomic number
            and use a keyword field with all elements to perform this search. This only
            works for elements (i.e. labels in ``CHEMICAL_SYMBOLS``) and quantities
            with this attribute.
        nested_quantity: To support optimade's 'zipped tuple' feature (e.g.
            'elements:elements_ratios HAS "H":>0.33), we use elasticsearch nested objects
            and nested queries. This quantity will provide the field for the nested
            object that contains the quantity (and others). The zipped tuples will only
            work for quantities that share the same nested object quantity.
    """

    name: str
    backend_field: Optional[str]
    length_quantity: Optional["ElasticsearchQuantity"]
    elastic_mapping_type: Optional[Field]
    has_only_quantity: Optional["ElasticsearchQuantity"]
    nested_quantity: Optional["ElasticsearchQuantity"]

    def __init__(
        self,
        name: str,
        backend_field: Optional[str] = None,
        length_quantity: Optional["ElasticsearchQuantity"] = None,
        elastic_mapping_type: Optional[Field] = None,
        has_only_quantity: Optional["ElasticsearchQuantity"] = None,
        nested_quantity: Optional["ElasticsearchQuantity"] = None,
    ):
        """Initialise the quantity from its name, aliases and mapping type.

        Parameters:
            name: The name of the quantity as used in the filter expressions.
            backend_field: The name of the field for this quantity in Elasticsearch, will be
                ``name`` by default.
            elastic_mapping_type: A decendent of an `elasticsearch_dsl.Field` that denotes which
                mapping type was used in the Elasticsearch index.
            length_quantity: Elasticsearch does not support length of arrays, but we can
                map fields with array to other fields with ints about the array length. The
                LENGTH operator will only be supported for quantities with this attribute.
            has_only_quantity: Elasticsearch does not support exclusive search on arrays, like
                a list of chemical elements. But, we can order all elements by atomic number
                and use a keyword field with all elements to perform this search. This only
                works for elements (i.e. labels in ``CHEMICAL_SYMBOLS``) and quantities
                with this attribute.
            nested_quantity: To support optimade's 'zipped tuple' feature (e.g.
                'elements:elements_ratios HAS "H":>0.33), we use elasticsearch nested objects
                and nested queries. This quantity will provide the field for the nested
                object that contains the quantity (and others). The zipped tuples will only
                work for quantities that share the same nested object quantity.
        """

        super().__init__(name, backend_field, length_quantity)

        self.elastic_mapping_type = (
            Keyword if elastic_mapping_type is None else elastic_mapping_type
        )
        self.has_only_quantity = has_only_quantity
        self.nested_quantity = nested_quantity

__init__(name, backend_field=None, length_quantity=None, elastic_mapping_type=None, has_only_quantity=None, nested_quantity=None)

Initialise the quantity from its name, aliases and mapping type.

Parameters:

Name Type Description Default
name str

The name of the quantity as used in the filter expressions.

 required
backend_field Optional[str]

The name of the field for this quantity in Elasticsearch, will be name by default.

 None
elastic_mapping_type Optional[Field]

A decendent of an elasticsearch_dsl.Field that denotes which mapping type was used in the Elasticsearch index.

 None
length_quantity Optional[ElasticsearchQuantity]

Elasticsearch does not support length of arrays, but we can map fields with array to other fields with ints about the array length. The LENGTH operator will only be supported for quantities with this attribute.

 None
has_only_quantity Optional[ElasticsearchQuantity]

Elasticsearch does not support exclusive search on arrays, like a list of chemical elements. But, we can order all elements by atomic number and use a keyword field with all elements to perform this search. This only works for elements (i.e. labels in CHEMICAL_SYMBOLS) and quantities with this attribute.

 None
nested_quantity Optional[ElasticsearchQuantity]

To support optimade's 'zipped tuple' feature (e.g. 'elements:elements_ratios HAS "H":>0.33), we use elasticsearch nested objects and nested queries. This quantity will provide the field for the nested object that contains the quantity (and others). The zipped tuples will only work for quantities that share the same nested object quantity.

 None
Source code in optimade/filtertransformers/elasticsearch.py 
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
def __init__(
    self,
    name: str,
    backend_field: Optional[str] = None,
    length_quantity: Optional["ElasticsearchQuantity"] = None,
    elastic_mapping_type: Optional[Field] = None,
    has_only_quantity: Optional["ElasticsearchQuantity"] = None,
    nested_quantity: Optional["ElasticsearchQuantity"] = None,
):
    """Initialise the quantity from its name, aliases and mapping type.

    Parameters:
        name: The name of the quantity as used in the filter expressions.
        backend_field: The name of the field for this quantity in Elasticsearch, will be
            ``name`` by default.
        elastic_mapping_type: A decendent of an `elasticsearch_dsl.Field` that denotes which
            mapping type was used in the Elasticsearch index.
        length_quantity: Elasticsearch does not support length of arrays, but we can
            map fields with array to other fields with ints about the array length. The
            LENGTH operator will only be supported for quantities with this attribute.
        has_only_quantity: Elasticsearch does not support exclusive search on arrays, like
            a list of chemical elements. But, we can order all elements by atomic number
            and use a keyword field with all elements to perform this search. This only
            works for elements (i.e. labels in ``CHEMICAL_SYMBOLS``) and quantities
            with this attribute.
        nested_quantity: To support optimade's 'zipped tuple' feature (e.g.
            'elements:elements_ratios HAS "H":>0.33), we use elasticsearch nested objects
            and nested queries. This quantity will provide the field for the nested
            object that contains the quantity (and others). The zipped tuples will only
            work for quantities that share the same nested object quantity.
    """

    super().__init__(name, backend_field, length_quantity)

    self.elastic_mapping_type = (
        Keyword if elastic_mapping_type is None else elastic_mapping_type
    )
    self.has_only_quantity = has_only_quantity
    self.nested_quantity = nested_quantity

Quantity

Class to provide information about available quantities to the transformer.

The transformer can use Quantity's to

  • do some semantic checks,
  • map quantities to the underlying backend field name.

Attributes:

Name Type Description
name str

The name of the quantity as used in the filter expressions.
backend_field Optional[str]

The name of the field for this quantity in the backend database, will be name by default.
length_quantity Optional[Quantity]

Another (typically integer) Quantity that can be queried as the length of this quantity, e.g. elements and nelements. Backends can then decide whether to use this for all "LENGTH" queries.
Source code in optimade/filtertransformers/base_transformer.py 
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
class Quantity:
    """Class to provide information about available quantities to the transformer.

    The transformer can use [`Quantity`][optimade.filtertransformers.base_transformer.Quantity]'s to

    * do some semantic checks,
    * map quantities to the underlying backend field name.

    Attributes:
        name: The name of the quantity as used in the filter expressions.
        backend_field: The name of the field for this quantity in the backend database, will be
            `name` by default.
        length_quantity: Another (typically integer) [`Quantity`][optimade.filtertransformers.base_transformer.Quantity]
            that can be queried as the length of this quantity, e.g. `elements` and `nelements`. Backends
            can then decide whether to use this for all "LENGTH" queries.

    """

    name: str
    backend_field: Optional[str]
    length_quantity: Optional["Quantity"]

    def __init__(
        self,
        name: str,
        backend_field: Optional[str] = None,
        length_quantity: Optional["Quantity"] = None,
    ):
        """Initialise the `quantity` from it's name and aliases.

        Parameters:
            name: The name of the quantity as used in the filter expressions.
            backend_field: The name of the field for this quantity in the backend database, will be
                `name` by default.
            length_quantity: Another (typically integer) [`Quantity`][optimade.filtertransformers.base_transformer.Quantity]
                that can be queried as the length of this quantity, e.g. `elements` and `nelements`. Backends
                can then decide whether to use this for all "LENGTH" queries.

        """

        self.name = name
        self.backend_field = backend_field if backend_field is not None else name
        self.length_quantity = length_quantity

__init__(name, backend_field=None, length_quantity=None)

Initialise the quantity from it's name and aliases.

Parameters:

Name Type Description Default
name str

The name of the quantity as used in the filter expressions.

 required
backend_field Optional[str]

The name of the field for this quantity in the backend database, will be name by default.

 None
length_quantity Optional[Quantity]

Another (typically integer) Quantity that can be queried as the length of this quantity, e.g. elements and nelements. Backends can then decide whether to use this for all "LENGTH" queries.

 None
Source code in optimade/filtertransformers/base_transformer.py 
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
def __init__(
    self,
    name: str,
    backend_field: Optional[str] = None,
    length_quantity: Optional["Quantity"] = None,
):
    """Initialise the `quantity` from it's name and aliases.

    Parameters:
        name: The name of the quantity as used in the filter expressions.
        backend_field: The name of the field for this quantity in the backend database, will be
            `name` by default.
        length_quantity: Another (typically integer) [`Quantity`][optimade.filtertransformers.base_transformer.Quantity]
            that can be queried as the length of this quantity, e.g. `elements` and `nelements`. Backends
            can then decide whether to use this for all "LENGTH" queries.

    """

    self.name = name
    self.backend_field = backend_field if backend_field is not None else name
    self.length_quantity = length_quantity