annosaurus 0.8.0

Added new endpoints for flexible queries:

• POST /anno/v1/fast/ - Retrieve annotations
• POST /anno/v1/fast/count - Retrieve a count of the annotations that match the query

Both of these accept a json body that defines various constraints. Any of these constraints can be omitted. Full examples are:

camelCase

{
  "videoReferenceUuids": [
      "43c8e033-eb22-4905-b39b-0a3e66a0075b"
  ],
  "concepts": [
    "Aegina",
    "Aegina citrea"
  ],
  "groups": [
      "ROV"
  ],
  "activities": [
      "descent",
      "transect"
  ],
  "observers": [
      "kwalz"
  ],
  "minDepth": 200,
  "maxDepth": 300,
  "minLatitude": 35.0,
  "maxLatitude": 37.0,
  "minLongitude": -122.7,
  "maxLongitude": -122.0,
  "minTimestamp": "1998-01-01T00:00:00Z",
  "maxTimestamp": "2021-01-07T00:53:32.757470Z",
  "linkName": "eating",
  "linkValue": "nil",
  "limit": 5000,
  "offset": 0,
  "data": true
}

snake_case

{
  "video_reference_uuids": [
      "43c8e033-eb22-4905-b39b-0a3e66a0075b"
  ],
  "concepts": [
    "Aegina",
    "Aegina citrea"
  ],
  "groups": [
      "ROV"
  ],
  "activities": [
      "descent",
      "transect"
  ],
  "observers": [
      "kwalz"
  ],
  "min_depth": 200,
  "max_depth": 300,
  "min_latitude": 35.0,
  "max_latitude": 37.0,
  "min_longitude": -122.7,
  "max_longitude": -122.0,
  "min_timestamp": "1998-01-01T00:00:00Z",
  "max_timestamp": "2021-01-07T00:53:32.757470Z",
  "link_name": "eating",
  "link_value": "nil",
  "limit": 5000,
  "offset": 0,
  "data": true
}

The response will be JSON in the form like:

{
    "query_constraints": {
        "video_reference_uuids": [
            "43c8e033-eb22-4905-b39b-0a3e66a0075b"
        ],
        "concepts": [
            "Aegina",
            "Aegina citrea"
        ],
        "observers": [
            "kwalz"
        ],
        "groups": [
            "ROV"
        ],
        "activities": [
            "descent",
            "transect"
        ],
        "min_depth": 200.0,
        "max_depth": 300.0,
        "min_timestamp": "1998-01-01T00:00:00Z",
        "max_timestamp": "2021-01-07T00:53:32.757470Z",
        "link_name": "eating",
        "link_value": "nil",
        "limit": 5000,
        "offset": 0,
        "data": true
    },
    "content": [
        {
            "ancillary_data": {
                "oxygen_ml_l": 1.125,
                "depth_meters": 299.3599853515625,
                "latitude": 36.701864,
                "temperature_celsius": 8.234999656677246,
                "theta": 3.799999952316284,
                "longitude": -122.050932,
                "phi": -3.299999952316284,
                "psi": 235.0,
                "pressure_dbar": 303.1000061035156,
                "salinity": 34.1609992980957,
                "altitude": 78.11000061035156,
                "light_transmission": 79.2699966430664,
                "uuid": "c34c0113-3aaa-4648-a704-3472f3f0f42d"
            },
            "observation_uuid": "5281db41-5914-4929-a298-48de0d26782d",
            "concept": "Physonectae",
            "observer": "kwalz",
            "observation_timestamp": "2013-11-25T19:52:38.957Z",
            "video_reference_uuid": "43c8e033-eb22-4905-b39b-0a3e66a0075b",
            "imaged_moment_uuid": "ab905fde-a8a1-4f23-b4bd-d28bf92a062e",
            "timecode": "00:45:56:04",
            "recorded_timestamp": "2013-11-08T15:11:58Z",
            "group": "ROV",
            "activity": "transect",
            "associations": [
                {
                    "link_name": "eating",
                    "link_value": "nil",
                    "to_concept": "Aegina",
                    "mime_type": "text/plain",
                    "uuid": "07a76fdb-11ff-437b-b2e4-4f7e312e806a"
                },
                {
                    "link_name": "comment",
                    "link_value": "wuzzle?",
                    "to_concept": "self",
                    "mime_type": "text/plain",
                    "uuid": "99fb539a-4578-46d2-aa8c-8a43e40e168f"
                }
            ],
            "image_references": []
        }
    ]
}

Here's a an example using curl:

curl --header "Content-type: application/json" \
    --request POST \
    --data '{"concepts": ["Aegina", "Aegina citrea"], "link_name": "eating", "limit": 5000, "offset": 0, "data": true}' \
    http://m3.shore.mbari.org/anno/v1/fast/

Notes

SQL expansion

Under the hood, concepts: ["Aegina", "Aegina citrea"] is expanded to the SQL (observation.concept IN ('Aegina', 'Aegina citrea') OR association.to_concept IN ('Aegina', 'Aegina citrea')

{concept: ["Aegina"], link_name: "eating"} is expanded to the SQL:

(
  observation.concept IN ('Aegina') OR 
  association.to_concept IN  ('Aegina')
) 
AND association.link_name = "eating"

Min params like minDepth are inclusive and so become AND ancillary_data.depth_meters >= minDepth in SQL. Max params are exclusive, i.e. maxDepth becomes AND ancillary_data.depth_meters < maxDepth