Introduction

Debugging in general is difficult - especially so if you're not using the right tools. This knowledgebase article provides a brief introduction to the tools available for debugging MarkLogic's semantic features, including the Optic API, SQL on MarkLogic Server, and SPARQL on MarkLogic Server.

Semantic Stack Debugging Tools

Unlike traditional MarkLogic searches, which do filtered or unfiltered searches after index resolution, queries in MarkLogic's semantic stack use an optimizer to generate a query plan.

1. For the optimizer:
   1. You can see your current optimizer settings in your logs if you enable the "Optic Optimization" and "Optic Statistics" (or their SPARQL counterparts, "SPARQL Cost Analysis" and "SPARQL Value Frequencies") trace events. Unfortunately, you won't be able to do much with these optimizer settings on your own - but MarkLogic Support will likely ask you for that output if you're running into issues with the optimizer for further debugging on our side.
   2. While you might not be able to change individual optimizer settings on your own, be aware that as an alternative you can remove the optimizer from the equation entirely by setting your query's optimization level to "optimize=0".
2. For the plan:
   1. You can output the relevant plan programmatically with op:explain, xdmp:sql-plan, or sem:sparql-plan.
   2. You can also output the plan to your logs by enabling the "Optic Plan" or "SPARQL AST" trace events.
   3. Plan output lets you know how many and what kind of joins are involved in your query, which will then enable you to consider ways to execute your query with fewer or more efficient joins if you're looking for more performance.
3. For requests in general, MarkLogic Server also provides Request Monitoring, which enables you to configure logging of information related to requests, including metrics collected during request execution.

Takeaways

• If you're looking to debug Optic, SQL, or SPARQL application code on your own, op:explain, xdmp:sql-plan, and sem:sparql-plan are your go-to tools to see how many and what kind of joins your query is currently using.
• If you need additional help, MarkLogic Support will ask you to enable the "Optic Optimization", "Optic Statistics", "Optic Plan", and "Optic Execution" trace events (or their SPARQL counterparts "SPARQL Cost Analysis", "SPARQL Value Frequencies", "SPARQL AST", and "SPARQL Execution").
• For customers using MarkLogic 10.0-8 or later, “Optic Summary” trace event is available. 

References:

• Knowledgebase: How to use Diagnostic Trace Events