Some hints for trying out DQL Explorer

Friday, March 8, 2019 at 4:46 PM UTC

Yesterday IBM released the prototype version of the DQL Explorer that was demoed some weeks ago at IBM Think by Luis Guirigay on OpenNTF and Github. Of course the interest was tremendous and so I was enthusiastic to test it out.

However, there are currently some caveats to deal with and this post explains what I found so far.

There are three different ways to get into the deploying process of the final application:

  • download the pre-built NSF file from OpenNTF
  • clone the repo from Github and also use the NSF file which is shipped here, too
  • clone the repo from Github, built the web component and assemble everything in the NSF

The third option also offers the possibility to run the web component in development mode which means that it runs independent form the NSF on your local machine and you can have a look into the source code, which is quite interesting. The problem is that I could not get it to work, I get errors when I try to access it on my local machine though I followed the instructions.

Regarding the web component’s source code: it’s written in Node.js and is using React as the UI renderer. I am not familiar with that stuff so there is something to learn.

On the other hand the NSF part is quite straight forward. It’s using Lotusscript agents for the REST calls and they execute the DQL queries. It has nothing to do with the Proton task and so you are able to run the NSF also on Windows machines.


After you put the NSF on your server you have to edit the two documents that come with it (in the view „Lookups“):

  • directories to search: you may want to remove the default value there but don’t leave it blank. Just put a / in the field
  • file names to include: here you can specify certain databases to work with if you don’t want to use a whole directory

But there are some issues I already documented:

  • using complex databases as a source may result in hangs of the „getdatabases“ agent or even a server crash
  • I had a database from which the agent returned fieldnames that were empty and this will end up in errors in the UI
  • it seems that special characters like / (a slash) in a field value also produce invalid JSON

The first issue occured with the fakenames NSF (or basically any other database which is based on the Domino Directory template). It seems to bee too complex to be scanned by the agent so the JSON will be too big to handle - I don’t know the actual reason for the error you get (the agent won’t be executed in a reasonable amount of time, though this will happen only after only a few seconds) or the server crash. I guess it’s a memory limitation for web agents written in Lotusscript. If you can please choose a much simpler database for the start. I used Theo’s Wine Tasting app again. It’s not the most interesting data structure there but it works.

For the second problem I used a database I created long ago that only contains a small subset of documents from the fakenames NSF and which is basically only to demo the Datatables JQuery plugin, so data structure is also not very interesting. However, there seems to be a problem reading field names from the forms. I recommend you to have a look into the agent’s code to see what’s going on there. I already added error handlers in all 3 agents.

The third was something I’ve seen today from Ulrich’s example and I can’t confirm on that, yet.

Anyway, make sure you set the ACL correctly (Anonymous shoudn’t be able to access the database) and sign it with an approriate ID.

For every app you want to search in you have to activate the design catalog by issueing the updall command:

load updall <database.nsf> -e
load updall <database.nsf> -d

If it’s all done, you should be able to access the app under


and it should look something like that:

Thanks to all who made this cool example possible! Smile




Latest comments to this post

Lothar wrote on 21.03.2019, 18:02

thanks for the post! Didn't know it wasn't calling PROTON, so I set it up on our Linux development server. No harm done, have improve my Linux knowledge anyways ;)

I'm seeing a few issues as well:

- view type queries are still executed as form type queries, judging by the outcome of developer options; tested it with node-demo.nsf (from the AppDevPack): querying the "state" column from "AllContactsByState" results in "State In ('CA', 'FL')"...

- building queries by form using a form with an alias that differs from the "readable" form name don't give me any fields to select from. If I rename the form so that the readable name = alias it works... (Also see post on openNTF)

 Link to this comment
George wrote on 15.03.2019, 08:20

Access dqlexplorer.nsf which was created from dqlexplorer.ntf shows empty. After replaced with shipped dqlexplorer.nsf, it works.

Somehow, it doesn't work for views but works fine with Forms.

 Link to this comment
Oliver Busse wrote on 09.03.2019, 12:05


no I used the vanilla NSF. Will try with the import.

 Link to this comment
Thomas Adrian wrote on 09.03.2019, 11:09

when I try to run the application locally using nodejs I am prompted for login, any ideas why?



 Link to this comment
Ulrich Krause wrote on 09.03.2019, 06:23

Oliver, have you re-imported the production build after npm run build?

The issue I have reported on twitter happens with the original "production" code in dqlexplorer.nsf. If I run the query against the "dev" version , (almost) everything works as expected.


 Link to this comment
Oliver Busse wrote on 08.03.2019, 22:33


well this one is a bit special, right? Wink

 Link to this comment
Thomas wrote on 08.03.2019, 22:21

thanks. not many repositories would run without an independant person explaining them. 

 Link to this comment

Leave a comment right here