Liquify Converts Queries to DataFaucet For You

Thanks to Rob Parkhill for helping me identify a source of confusion for people interested in learning DataFaucet.

There's a tool in the DataFaucet documentation called "liquify". You can see the liquify page on the public site here where you can enter in a query from your application and when you submit the form it will show you how you can create that same query with the DataFaucet syntax. Like any tool of this nature it can't be perfect, although it should be able to convert the majority of queries. Primarily this tool is designed as a "learning aid" to help you get a feel for the syntax of DataFaucet by seeing the the before and after with your own queries from SQL to DataFaucet (and don't ask me how long I spent writing it!) :)

One of the more difficult challenges of publishing any software API is knowing how to write the documentation. In an ideal world, there would always be a separate technical writer handling documentation issues, conferring with the programmers to ensure his documentation is correct. But this begs the question, "isn't that adding more work? Wouldn't it be easier for the programmers to write their own documentation?"

In some ways this is true - the programmer already knows the system and so they don't have to ask questions about it, because they already know the answers. And that may save some time. The problem however lies in the fact that those questions don't get asked. And because those questions don't get asked, it's very easy for a programmer like myself to accidentally omit vital information when writing documentation for their own API. This happens precisely because we are so familiar with the system already that we don't know what questions an outside observer might ask. The end result is that we usually end up taking some things for granted.

The issue that Rob Parkhill helped me uncover is one of these issues of too much familiarity.

Originally the liquify tool would check the provided code for a cfquery tag with a name attribute and if it found a name, it would create code that would return a query, like this:

Now that looks fine (although you may personally like to remove the cfscript tags). You had originally created a query called "myQuery" and then the returned code also created the same query. But what if, seeing the liquify tool for the first time you didn't notice the comment at the top of the page that said you could include your cfquery tags, and made an intuitive guess that you should just include your sql code and not the cfquery tags. That's a logical assumption isn't it?

The difference here is pretty subtle. And looking at this output from liquify, you might think "great, there's my query in that stmt variable." Again having not seen it before, that's a pretty logical guess. It wouldn't work though because where ds.select() returns a query, ds.getSelect() returns an object.

The problem is that I hadn't anticipated this logical progression from newcomers. When I looked at the above code, I merely said to myself "ahh, there's no name for the query, so I can't create a query variable, I can only create a statement object". That made perfect sense to me because I was already familiar with the system. But if you try to use that stmt object as a query, you're going to get an ugly error message from ColdFusion telling you it's not a query. And if you're not already familiar with object-oriented (OO) concepts you might also not immediately realize that you need to execute the statement with stmt.execute() to get your query.

So to help clarify, I've modified the Liquify tool slightly so that it will always create a query for select statements.