[Query interface] Number of query methods

[rubensworks]

This issue branches of from the discussion in https://github.com/rdfjs/query-spec/issues/5#issuecomment-931370498

In essence, the question is to either expose a single query methods such as

      query(query: string): Promise<SomeUnionType>

or expose multiple methods such as

      select(query: string): Promise<Array<Record<string, import('rdf-js').Term>>>
      construct(query: string): Promise<import('rdf-js').Dataset>
      ask(query: string): Promise<boolean>
      update(query: string): Promise<void>

(I will add my own thoughts as a comment in a bit...)

[jacoscaz]

@rubensworks good idea branching into a separate issue.

I will not even comment on ORMs because that is the worst comparison ever

That's fair, I should not have mentioned ORMs as that comparison is not a good one, indeed.

I'm curious about this statement. In what scenarios is it not known what is the desired kind of result? (tabular, graph or boolean).

User-provided query strings, for example.

What is the nature of this coupling?

Please correct me if I misunderstood your comment but I think there's a non-trivial difference between having per-query-type methods and per-expected-result-type methods. The latter kind would allow the interface to support more than one query language, for example, which IMHO would be a good thing considering @gsvarovsky's JSON-RQL and @rubensworks's GRAPHQL-LD. With per-query-type methods, instead, you'd be bound to SPARQL query types.

[rubensworks]

I've been tinkering in Comunica with the idea of having multiple query methods as well. Because I agree that a single query method may not be very user-friendly, as it may require some form of casting.

However, as @jacoscaz brought up, there are also some downsides to multiple methods, such as delayed query type determination within the query engine (relevant for JSON-RQL and GraphQL-LD).

Another disadvantage of multiple methods is that if you are making a library that delegates things from one query engine to another, then you have to do this delegation in all the methods, instead of having to do it only once.

---

If we stick with the single query method, I see two options for still allowing a higher level of user-friendliness:

1. Make the single query method required, and the return-type-specific methods optional.
2. Only make the single query method required, and have a convenience library on top of it that adds return-type-specific methods.

To keep the spec as simple and minimal as possible, my current preference goes out to option 2.

[gsvarovsky]

To put a different spin on @jacoscaz's point, we are discussing several axes:

• query form
• query syntax (string or algebra)
• query language (SPARQL, json-rql, graphql-ld).

Languages may be to a greater or lesser extent just syntaxes themselves, but may also be quite different to SPARQL in their intended usage patterns and return types.

Personally I think it may be too much to try and generalise over query languages, with the cut-off point being whether the return type is different to SPARQL. By that yardstick, this API should cover strings and algebra (returning quads and bindings), but not json-rql and graphql-ld (returning JSON).

For query form, my preference is for a single overloaded method (e.g. my interface 😇), primarily for readability, because the parameter will usually be sufficiently typed by itself, e.g.

store.query("DESCRIBE ?book WHERE ...")
store.query(Algebra.createDescribe(...))
store.query(describeBooks)

[jacoscaz]

Personally I think it may be too much to try and generalise over query languages, with the cut-off point being whether the return type is different to SPARQL. By that yardstick, this API should cover strings and algebra (returning quads and bindings), but not json-rql and graphql-ld (returning JSON).

@gsvarovsky this sounds very reasonable to me. My use case is only about SPARQL and therefore support for other query languages doesn't affect my work. If you and @rubensworks, who actually work with other query languages, are ok with keeping this SPARQL-focused then I am happy follow your lead.

I've considered @tpluscode 's suggestion of having per-expected-return-type methods and briefly experimented with it by augmenting quadstore's API to get a feel of how that would work in everyday life. Ultimately, however, I prefer the simplicity of the single method + return type metadata approach.

[jacoscaz]

We've recently merged #7, which includes and elaborates upon what was discussed in this issue. I think we can close this in favor of more focused issues - @rubensworks final word up to you!