Err embedding when multiple relationships found

[steve-chavez]

When having one-to-many relationships like:

(Where person_detail is a view of person)

This request:

GET /message?select=*,sender(*)

Is ambiguous. Both person or person_detail could be embedded.
Until now we have returned the first detected relationship but with this PR we would return a 300 Multiple Choices error with this body:

{
  "details": [
  {
    "cardinality": "Parent",
    "source": "test.person[id]",
    "target": "test.message[sender]"
  },
  {
    "cardinality": "Parent",
    "source": "test.person_detail[id]",
    "target": "test.message[sender]"
  }
  ],
  "hint": "Disambiguate by choosing a relationship from the `details` key",
  "message": "More than one relationship was found for message and sender"
}

So, for the request to succeed, the user would have to disambiguate by following the details info:

GET /message?select=*,person_detail!sender(*)

Or:

GET /message?select=*,person!sender(*)

This gets more helpful when there are more complex relationships. The aim of this PR is to formalize the disambiguation capabilities we have.

As it is now, the disambiguation syntax is hard to grok and the duck typing stuff is hard to explain and document. We get frequent questions about this on gitter chat.

This will also help for future features like #818, were a wrong embed would result in a more serious error.

This PR would imply a breaking change.

(Related to #1230)

[steve-chavez]

The aim is to have this syntax for disambiguation:

GET /message?select=*,<table>!<fk_column>!<cardinality>(*)

Specifying the cardinality is needed for cases like self reference relationships where there would always be a parent and child relationship. A prototype of this can be seen here. The cardinality values would be: o2m, m2m and m2o.

I think that syntax would cover all of the ambiguous cases(fk_column could take a list later).

For that we'd have to remove duck typing. Currently that feature makes up for some confusing errors:

GET /tasks?select=id,name,project(id)

  {
   "hint":"Disambiguate by choosing a relationship from the `details` key",
   "details":[
     {"cardinality":"Child","source":"test.projects[id]","target":"test.tasks[project_id]"},
     {"cardinality":"Child","source":"test.materialized_projects[id]","target":"test.tasks[project_id]"},
     {"cardinality":"Child","source":"test.projects_view[id]","target":"test.tasks[project_id]"},
     {"cardinality":"Child","source":"test.projects_view_alt[t_id]","target":"test.tasks[project_id]"}],
    "message":"More than one relationship was found for tasks and project"
  }

Using select=projects(*) instead of select=project(*) in this case results in a single relationship found.

These enhancements would be done in another PR.

[steve-chavez]

I'll continue with the disambiguation improvements in another PR.

For now I think the error message is good for merging.