Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. Join them; it only takes a minute:

Sign up
Here's how it works:
  1. Anybody can ask a question
  2. Anybody can answer
  3. The best answers are voted up and rise to the top

I'm tinkering with a query abstraction over WebSQL/Phonegap Database API, and I find myself both drawn to, and doubtful of, defining a fluent API that mimics the use of natural English language grammar.

It might be easiest to explain this via examples. The following are all valid queries in my grammar, and comments explain the intended semantic:

//find user where name equals "foo" or email starts with "foo@"

//find user where name equals "foo" or "bar"

//find user where name equals "foo" or ends with "bar"

//find user where name equals or ends with "foo"

//find user where name equals "foo" and email is not like ""

//where name is not null

//find post where author is "foo" and id is in (1,2,3)
find("post").where("author").is("foo").and("id").is().in(1, 2, 3);

//find post where id is between 1 and 100

Edit based on Quentin Pradet's feedback: In addition it seems, the API would have to support both plural and singular verb forms, so:

//a equals b

//a and b (both) equal c

For the sake of question, let's presume that I haven't exhausted all possible constructs here. Let's also presume that I can cover most correct English sentences - after all, the grammar itself is limited to the verbs and conjuctions defined by SQL.

Edit regarding grouping: One "sentence" is one group, and the precedence is as defined in SQL: left to right. Multiple groupings could be expressed with multiple where statements:

//the conjunctive "and()" between where statements is optional

As you can see, the definition of each method is dependent on the grammatical context it is in. For example the argument to "conjunction methods" or() and and() can either be left out, or refer to a field name or expected value.

To me this feels very intuitive, but I would like you hear your feedback: is this a good, useful API, or should I backpedal to more straighforward implementation?

For the record: this library will also provide a more conventional, non-fluent API based on configuration objects.

share|improve this question

migrated from Mar 1 '13 at 15:04

This question came from our site for peer programmer code reviews.

Chaining is also why jQuery is very famous. Pretty straight-forward, sequential, and understandable. – Joseph the Dreamer Mar 1 '13 at 15:02
This is interesting! You should probably ask this on programmers. – Benjamin Gruenbaum Mar 1 '13 at 15:03
How would you handle grouping? The equivalent of: ... where foo = 1 or (bar = 2 and qux = 3)? – user40980 Mar 1 '13 at 15:07
IMO this kind of fluent API is horrible. For example lack of operator precedence is annoying. I'd parse where("name").equals("foo").or("bar") as (name=="foo")or bar. Then it's not clear when a string represents a literal, and when it presents a column name,... – CodesInChaos Mar 1 '13 at 15:22
btw. if you want to use a DSL for querying a database, you could use the already existing DSL called SQL. – CodesInChaos Mar 1 '13 at 15:23
up vote 18 down vote accepted

I think it's very wrong. I study natural langage and it's full of ambiguity that can only be resolved with context and a lot of human knowledge. The fact that programming languages are not ambiguous is a very good thing! I don't think you want meaning of methods to change according to context:

  • This is adds more surprises since you bring ambiguity
  • Your users will want to use constructions that you will not have covered, eg. find("user").where("name").and.("email").equals("foo");
  • It's hard to report errors: what can you do with find("user").where("name").not().is().null();?

Let's also presume that I can cover most correct English sentences - after all, the grammar itself is limited to the verbs and conjuctions defined by SQL.

No, you can't cover most correct English sentences. Others have tried before, and it gets very complicated very quickly. It's called Natural language understanding but nobody really tries that: we're trying to solve smaller problems first. For your library, you basically have two options:

  • either you restrict yourself to a subset of English: that gives you SQL,
  • or you try to cover "English" and you find out that it's not possible due to the ambiguity, complexity and diversity of the language.
share|improve this answer
Thanks for your input. Edited my question to cover the first case you listed and added some caveats. I agree with your position on ambiguity - that's the crux of my question. Is is acceptable for programming languages to be ambious in well-defined contexts? – fencliff Mar 1 '13 at 15:15
if it is ambiguous, it is not well-defined. If it is ambiguous, there is more than one potential outcome, and something has to pick one of them. Either the choice will be well-defined, or the language parser will pick at random. So,ambiguity in a programming language is okay if you want a stochastic language (1+1 might equal 2, and sometimes might equal 1 or 3) as opposed to deterministic (1+1 always equals 2). – Michael Paulukonis Mar 1 '13 at 15:52
Are you talking about his proposal or English? Most of the time, ambiguity can be resolved using context and/or knowledge (part of which is common sense), something that is not available to a computer. – Quentin Pradet Mar 1 '13 at 15:58
+1 Good catch on the context sensitivity of his particular implementation of a fluent API. I liked the idea of his fluent API at first glance but didn't look so closely to see this. Definitely huge problem. – Jimmy Hoffa Mar 2 '13 at 2:40

In addition to Quentin Pradet's very good points, I am doubtful of the alleged benefits of this language.

Presumably the point of a grammar close to natural language is to make it accessible. But SQL already is quite close to natural language. Is one of these really closer to English than the other?


select user from table where name = 'foo'

I don't really see the benefit of your grammar, from a standpoint of intuitiveness or readability. In fact, the SQL version looks more readable (and is easier to type) because of its whitespace.

share|improve this answer

There are a number of bad less than ideal design decisions that appear to have been made in considering this API.

The first is the question of utility - what purpose does it serve? This appears to be creating a data structure that will compile into a dialect of SQL. Incidentally, the grammar appears to be a limited set of SQL. The question of "what advantage does this serve over just using SQL?" becomes key. If it is more cumbersome to write using the fluent interface than just writing a string with the appropriate interpolation in it then one won't write using this API.

English is ambiguous. Attempting to model a fluent interface on English is a poor choice (you are better off using Latin). When there are multiple possibly valid parsings of the same set of chain of calls, this leads to confusion and surprise. Neither of these are good things to have in an API.

There are more parts to SQL than this API is exposing. Joins (in any of their myriad forms) are notably absent form the example set. Subqueries (foo in (select id from bar)), unions, and group by are a few of the things that are often used. Complex groupings of logic do not appear to be present in any intuitive way.

If one was writing using this API and then found that the API is not capable of expressing the desired query, significant time will be lost. It is a poor choice to be using mixed styles for doing a queries in an application (simple queries in this api, complex in raw sql) - and ultimately the one that is more expressive will be used.

While programming is widespread, English fluency is not. Even with a limitation of the language to "SQL like" there are nuances of how a native speaker would read something and someone who has English as a second or third language.

There is unnecessary redundancy in the API for the sake of English. In particular equal() vs equals() doing the same thing. While I am not certain of it, I believe that is() is a no-op added for sake of a matching English closer. I welcome any to listen to my ranting about redundancy of methods in ruby in chat - don't make the same mistake.

Sit down and write out a comprehensive example set of the queries you want to be able to use. Determine who you will handle all of those examples in a non-ambiguous way that is less cumbersome than the queries themselves. If you can't, consider if it is worthwhile to go down the path of writing the API. SQL is where it is today (it isn't perfect, but I haven't found anything better) over decades of refinement.

RFC 1925 - The Twelve Networking Truths

(12) In protocol design, perfection has been reached not when there is nothing left to add, but when there is nothing left to take away.

share|improve this answer

I tend to somewhat agree with others' posts that this is not a great design. However, I believe I have different reasons.

You're presenting what I view as a concrete syntax for SQL queries. I strongly believe that concrete syntax can never help a language, only hurt if it is bad.

However, abstract syntax is a different story. Abstract syntax defines the structure of your language and how phrases may be combined to build bigger phrases. I feel that the success of a language strongly depends on the quality of its abstract syntax definition.

My problem with the fluent API isn't that it's ambiguous, or unclear, or not expressive -- it's that it hides the real language and its structure, and in so doing, ends up making things much more complicated than they have to be (by introducing ambiguities, non-obvious syntax errors, etc.).

Since you mentioned that you'll also provide a "more conventional API", it sounds like you already know all this. To that I say "Good!" But that doesn't mean that you can't also develop your fluent API in parallel! A single abstract syntax definition can support multiple concrete syntaxes. While you should keep in mind that the abstract syntax is the real deal, a concrete syntax can also be very helpful.

share|improve this answer

Your Answer


By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.