Have you ever run some code in Query Console only to realize that your query was going to take way too long to finish? Perhaps you made a mistake and didn't want to wait for the query to complete. If you canceled the browser request, that would end the connection, but it wouldn't end the program invocation (called a "request") on the MarkLogic side. It would continue to run until the execution is complete.
Most of the time, this isn't really an issue. The server, of course, is multi-threaded, handling many concurrent transactions. Just cancel the browser request, move on, and let the query finish when it finishes. But sometimes it becomes necessary to free up server resources by killing the query and starting over. To do this, you need access to the Admin interface. I'm going to walk you through this. It's simple once you know where to look.
First, I'll run a pathological query. Don't try this at home (at least not on any production machines)!
This is asking for 1,000,000 random documents—in other words, trouble. Needless to say, this will take a long time to execute, leaving us plenty of time to figure out how to cancel the query. One brute-force way to stop executing it would be to restart MarkLogic Server (and that's probably what I did before I knew better.) But that's unnecessary.
Go to the Administrative interface (at http://localhost:8001/ if you're running MarkLogic locally). At the top of the screen, you'll see a tab labeled "Status." Click that:
This will take you to the "System Status" screen. This page reveals status information about hosts, databases, forests, and app servers. The App Server section is what we're concerned with. Scanning down the "Queries" column, we see that the "Admin" server is processing a query (namely, the one that generated the page we see). Everything looks okay so far. But just below that, we see that the "App-Services" server is just over 3 minutes into processing a query. That's our slow one. Query Console runs on the "App-Services" app server, which explains why we see it there. Go ahead and click the "App-Services" link:
This takes us to the "App-Services" status page. So far, there's still no "cancel" button. One more click will reveal it ("show more"):
And voila! We now see an individual entry for the currently running query. Here we see it's called "eval.xqy"; that's the query module that Query Console invokes when you submit a query. If you were running your own query module (instead of using Query Console), then you would see its name here instead. To cancel the query, click the "[cancel]" link:
One more click (on the confirmation page), and we're home free:
This takes us back to the status page, where we see MarkLogic Server is in the process of canceling our query:
A quick refresh of the page shows that the query is as good as gone:
What happens if you forget to cancel a query? Will MarkLogic keep on trucking forever, doing what you told it to do? No, this depends on your configuration, but your query will reach a time limit, at which point the Server will cancel the query for you. For example, here's what Query Console eventually returns back if I don't bother canceling the query:
How long is this time limit? Well, that depends on your server configuration. You can actually set the timeout in the query itself, using the xdmp:set-request-time-limit() function, but even that will be limited by your server's "max time limit." For example, on the "Configure" tab of my "App-Services" app server, you can see that the "default time limit" is set to 10 minutes (600 seconds), and the highest any query can allow itself to go (by setting its own request time limit) is one hour (3600 seconds):
If you're thinking to yourself, "Yes! Now I can run those really slow queries without them getting automatically killed!" I would suggest to you that there is a better way. If you have queries that run that long, then run, do not walk, to the Developer mailing list (which you can easily subscribe to by signing up as a Community member), or post your question on Stack Overflow, tagging it with "marklogic". I think you'll find that your time doing either of these is well spent (it might even make your day!).