Document jmespath for filtering metadata

[danielballan]

https://jmespath.org/

[danielballan]

This is implemented. It was rushed for internal NSLS-II requirements. Needs tests, docs. Also, we need to consider how to expose this in the Python client with some additional client-side API.

Demo:

$ http 'https://tiled-demo.blueskyproject.io/entries/bmm?page[limit]=3&select_metadata=summary&fields=metadata'
HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 529
Content-Type: application/json
Date: Tue, 02 Nov 2021 12:37:13 GMT
Server: nginx/1.18.0 (Ubuntu)
cache-control: must-revalidate
content-encoding: gzip
etag: a189d006dc7b52f1a3b4a933d320a66f
server-timing: acl;dur=0.1, tok;dur=0.1, pack;dur=0.0, compress;dur=0.1;ratio=3.5, app;dur=8.4
set-cookie: tiled_csrf=NzBlhbaVA2ZvVpN79cdx7XBnZCrPeBK-47-r0G1Np8M; HttpOnly; Path=/; SameSite=lax
vary: Accept-Encoding

{
    "data": [
        {
            "attributes": {
                "count": null,
                "metadata": {
                    "datetime": "2020-03-03T04:18:06.829518",
                    "duration": 705.9699432849884,
                    "plan_name": "scan_nd",
                    "scan_id": 22521,
                    "stream_names": [
                        "baseline",
                        "primary"
                    ],
                    "timestamp": 1583209086.8295176,
                    "uid": "f8c83910-4adb-4207-a465-9ff0ff0e9cd2"
                },
                "sorting": null,
                "specs": null
            },
            "id": "f8c83910-4adb-4207-a465-9ff0ff0e9cd2",
            "links": {
                "search": "http://localhost:8000/search/bmm/f8c83910-4adb-4207-a465-9ff0ff0e9cd2",
                "self": "http://localhost:8000/metadata/bmm/f8c83910-4adb-4207-a465-9ff0ff0e9cd2"
            },
            "meta": null,
            "type": "tree"
        },
        {
            "attributes": {
                "count": null,
                "metadata": {
                    "datetime": "2020-03-03T04:33:05.443115",
                    "duration": 699.2554874420166,
                    "plan_name": "scan_nd",
                    "scan_id": 22524,
                    "stream_names": [
                        "baseline",
                        "primary"
                    ],
                    "timestamp": 1583209985.4431148,
                    "uid": "51f9eb19-d38b-4789-81df-6988de1db04c"
                },
                "sorting": null,
                "specs": null
            },
            "id": "51f9eb19-d38b-4789-81df-6988de1db04c",
            "links": {
                "search": "http://localhost:8000/search/bmm/51f9eb19-d38b-4789-81df-6988de1db04c",
                "self": "http://localhost:8000/metadata/bmm/51f9eb19-d38b-4789-81df-6988de1db04c"
            },
            "meta": null,
            "type": "tree"
        },
        {
            "attributes": {
                "count": null,
                "metadata": {
                    "datetime": "2020-03-03T04:45:06.373420",
                    "duration": 695.1129577159882,
                    "plan_name": "scan_nd",
                    "scan_id": 22525,
                    "stream_names": [
                        "baseline",
                        "primary"
                    ],
                    "timestamp": 1583210706.37342,
                    "uid": "d96c0436-2718-43ea-90f5-c21a77a89575"
                },
                "sorting": null,
                "specs": null
            },
            "id": "d96c0436-2718-43ea-90f5-c21a77a89575",
            "links": {
                "search": "http://localhost:8000/search/bmm/d96c0436-2718-43ea-90f5-c21a77a89575",
                "self": "http://localhost:8000/metadata/bmm/d96c0436-2718-43ea-90f5-c21a77a89575"
            },
            "meta": null,
            "type": "tree"
        }
    ],
    "error": null,
    "links": {
        "first": "/entries/bmm?page[offset]=0&page[limit]=3",
        "last": "/entries/bmm?page[offset]=123&page[limit]=3",
        "next": "/entries/bmm?page[offset]=3&page[limit]=3",
        "prev": null,
        "self": "/entries/bmm?page[offset]=0&page[limit]=3"
    },
    "meta": {
        "count": 123
    }
}

Demo of error handling:

$ http 'https://tiled-demo.blueskyproject.io/entries/bmm?page[limit]=3&select_metadata=.summary&fields=metadata'
HTTP/1.1 400 Bad Request
Connection: keep-alive
Content-Length: 165
Content-Type: application/json
Date: Tue, 02 Nov 2021 12:37:00 GMT
Server: nginx/1.18.0 (Ubuntu)
server-timing: acl;dur=0.1, app;dur=12.0
set-cookie: tiled_csrf=QnxpX6maHnz8u5UBTfOm_aRVBy16A0uKbZ8NHKwE8GY; HttpOnly; Path=/; SameSite=lax

{
    "detail": "Malformed 'select_metadata' parameter raised JMESPathError: invalid token: Parse error at column 0, token \".\" (DOT), for expression:\n\".summary\"\n ^"
}