MarkLogic Pulse for VS Code

Develop, run, and debug MarkLogic code in Visual Studio Code.

MarkLogic Pulse (ml-pulse) is a VS Code extension with code intelligence, query evaluation, and debugging for MarkLogic-native languages — XQuery, Server-Side JavaScript (.sjs), SQL, SPARQL, Optic, and GraphQL.

Report a bug or request a feature: Open an issue on the public tracker (ml-pulse-vscode-issues). The extension source repository is private.

---

Requirements

• Visual Studio Code 1.78+
• A reachable MarkLogic instance with a REST app server (default port 8000)
• For JS debugging: MarkLogic 10.0-4+

---

Install

1. Install MarkLogic Pulse from the Marketplace, or Install from VSIX… with a built ml-pulse-x.y.z.vsix.
2. Run Developer: Reload Window after install or upgrade.

---

Getting started

1. Command Palette → ML Pulse: Open Connection Form.
2. Enter host, REST port, username, password (and optional documents/modules DB, SSL, Modules URI prefix).
3. Save & Activate, then Test.
4. Open an .xqy / .sjs / .sql / .rq / .graphql file and press Ctrl+Alt+Enter (Mac: Cmd+Alt+Enter) to eval. Select text first to eval only the selection.

Useful first commands:

• ML Pulse: Eval XQuery / Eval JS / Eval SQL / Eval SPARQL
• ML Pulse: Submit Optic Query - Return JSON (CSV / XML variants available)
• ML Pulse: Submit GraphQL Query
• ML Pulse: Run Connection Doctor
• ML Pulse: Deploy Current Module (push the active module to the modules DB)

---

Connection & security

What it does

Named connection profiles, a Connection Form UI, Connection Doctor, and passwords stored in VS Code SecretStorage (not plaintext settings).

Configure

1. ML Pulse: Open Connection Form — preferred way to set host, ports, auth (DIGEST / BASIC / CLOUD), SSL, documents DB, modules DB, app server, and Modules URI prefix.
2. ML Pulse: Save Current Connection as Profile — named entry under marklogic.profiles.
3. ML Pulse: Set MarkLogic Password / Clear Stored Password — SecretStorage for the active profile.
4. ML Pulse: Switch Connection Profile / Rename / Delete.
5. marklogic.activeProfile selects which profile overrides default marklogic.* settings.

Modules URI prefix: If your modules DB stores URIs under a deploy root (e.g. /deploy/modules/appserver-root/...) while workspace paths look like .../appserver-root/xquery/..., set Modules URI prefix on the Connection Form (saved with the profile). That maps static-check imports, deploy on save, and softens XDMP-MODNOTFOUND when the file exists on disk but the DB URI needs the prefix.

How to use

1. Open Connection Form → fill values → Save & Activate → Test.
2. Switch profiles from the Command Palette when jumping between environments.
3. Run ML Pulse: Run Connection Doctor if REST/Manage/auth look wrong.

---

Eval / results

What it does

Evaluate XQuery, JavaScript, SQL, SPARQL, Optic (JSON / CSV / XML), and GraphQL against the active REST app server. Results appear in the ML Pulse → Results panel (or an editor tab if configured), with history, copy, and export.

Configure

Setting	Purpose
marklogic.resultsInEditorTab	Prefer an editor tab for results
marklogic.resultsHistory.maxEntries	Cap for results history
marklogic.sql.results	SQL result shape (when applicable)

How to use

1. Open a query file (or select a fragment) → Ctrl+Alt+Enter (language-aware eval) or the matching ML Pulse: Eval … command.
2. Optic JSON: Ctrl+Alt+Shift+Enter, or Command Palette CSV / XML variants.
3. View ML Pulse → Results; use Copy (Ctrl+Alt+Shift+C), Export (Ctrl+Alt+Shift+S), Clear, Focus.
4. Show Query Results History (Ctrl+Alt+H) to reopen a prior result.

Right-click the editor for the same eval commands. Inline Eval CodeLens play buttons are not used — palette and keybindings only.

---

XQuery intelligence

What it does

Completions (MarkLogic APIs, local + imported symbols), snippet insert for required params, Signature Help, Hover docs, Outline, Go to Definition, Find References, Rename, reference-count CodeLens, structural + house-style lint, Format Document, and MarkLogic static-check diagnostics (ml-pulse-compile) with Copy / Explain.

A Module Symbol Index and modules path index warm in the background so import prefixes (hw:, $hw:…) and Go to Definition stay responsive while you type.

Configure

Setting / field	Purpose
Connection Form → modules DB	Where static-check resolves import … at
Connection Form → Modules URI prefix	Deploy-root prefix for modules DB URIs
marklogic.modulesRootDir	Workspace folder that mirrors modules root (helps relative at rewrite)
marklogic.lint.enabled	Local lint on/off
marklogic.lint.strictStyle	House-style rules (version, at, types, …)
marklogic.lint.serverValidate	MarkLogic static-check on save/idle
marklogic.lint.serverValidateOnIdleMs	Idle debounce for server validate

Format-on-save for XQuery is off by default (use Format Document explicitly).

How to use

1. Open a workspace with modules (e.g. repo test-app) and wait briefly for indexes.
2. Type hw: / hw:hel after an import module → accept a function → Tab through required args only.
3. F12 / Ctrl+Click calls, $vars, and import … at "…" paths.
4. Shift+F12 / reference CodeLens for workspace uses.
5. Lightbulb on ml-pulse Problems → Quick Fix / Fix All; on compile errors → Copy / Explain.
6. Save (with connection + serverValidate) to see MarkLogic static-check in Problems. Library modules use an import stub (no false XDMP-EVALLIBMOD).

---

SJS intelligence

What it does

Same pattern for .sjs: completions / Signature Help / Hover for locals and require aliases, Outline (including Optic chains), Go to Definition on functions and require paths, Find References + CodeLens, lint (prefer require over ES import, 'use strict', …), Format Document, and optional format-on-save.

Configure

• Same connection / modules settings as XQuery where imports map to the modules DB.
• marklogic.format.formatOnSave — format .sjs on save (default off unless you enable it).
• Lint toggles shared with XQuery (marklogic.lint.*).

How to use

1. const lib = require('/javascript/library') then type lib. → accept hello(friend) with tabstops.
2. F12 on hello( or the require path; Rename works on function / exports / local bindings (shadow-aware).
3. Format Document / save as configured; Fix All for safe lint edits.
4. Save with connection + serverValidate for MarkLogic static-check; missing require that exists on disk may tip Modules URI prefix / deploy instead of a hard false red.
5. Snippets: ml-sjs-module, ml-sjs-try, …

---

SQL / SPARQL / Optic / GraphQL

What it does

Keyword/snippet completions; SQL/Optic catalog refresh (schemas, views, columns) and CTE/table navigation; Optic method and catalog-backed fromView / col hints in .sjs and XQuery op: chains; Rows API eval (JSON/CSV/XML); GraphQL submit; SPARQL eval and optional graph sketch.

Configure

• Active connection for live SQL/Optic catalog / eval.
• ML Pulse: Refresh SQL/Optic Catalog after schema or TDE changes (also runs after successful TDE Studio Insert).

How to use

1. .sql → eval; Refresh SQL/Optic Catalog → complete/jump table names.
2. .rq / .sparql → Eval SPARQL; Show SPARQL Graph when exploring.
3. Optic .sjs or .xqy → Submit JSON/CSV/XML (Ctrl+Alt+Shift+Enter for JSON); Explain Active Query for plans.
4. Completing inside fromView(' / op:from-view(' uses the catalog; F12 on a view can jump to a matching open TDE template.
5. .graphql / .gql → Submit GraphQL Query.

---

Optic intelligence

What it does

End-to-end Optic authoring on top of SJS and XQuery: outline of fromView / op:from-view / columns / chain methods; catalog completions; soft diagnostics for missing .result() / op:result() and unknown views when the catalog is live; explain rewrite for both hosts.

How to use

1. Refresh the SQL/Optic catalog.
2. Write or open callOptic.sjs / callOptic.xqy from test-app.
3. Use Outline, completions, Explain, and Submit Optic as above.

---

Debugging

What it does

Interactive JS (.sjs) and XQuery (.xqy) debug: connect a debug server, then launch (evaluate current module) or attach to an in-flight request. Editor breakpoints, step/continue, stack, and variables work for both adapters.

Configure

• MarkLogic 10.0-4+ for JS debug.
• Workspace marklogic.* connection settings (eval + debug-my-requests / debug-any-requests privileges).
• In launch.json, set root to your local modules tree so imports map for breakpoints/stack (both JS and XQuery). Use program only to launch a specific file. Prefer root over deprecated JS path.
• Command Palette → Connect JavaScript Debug Server / Connect XQuery Debug Server.
• Use launch configs labeled ML Pulse JS Debugger / XQY Debugger (launch and attach templates ship with the extension).

How to use

1. Connect the matching debug server (JS or XQuery).
2. Open a .sjs or .xqy module, set breakpoints.
3. Start a launch (current module) or attach config from the Run and Debug view; pick a paused request when attaching.
4. Step / continue; inspect Variables and (for XQuery) Debug Console / watches with $name or a simple name.
5. Disconnect … Debug Server when finished. See docs/debugging-support/ for deeper setup and known limits (no cross-language stepping, no set-variable).

---

Modules browser

What it does

Browse MarkLogic modules via a virtual file system; optional gated write (confirm + dry-run). Separately, deploy on save (opt-in) and Deploy Current Module push workspace files under the modules root to the modules DB.

Configure

Setting	Purpose
marklogic.deployOnSave.enabled	On save, deploy files under modules root to the modules DB (off by default)
marklogic.modulesRootDir	On-disk modules root (also used for deploy URI mapping)
marklogic.modulesUriPrefix	Deploy URI prefix when DB paths include a deploy root
marklogic.modulesFs.writeEnabled	Allow writes through the modules FS
marklogic.modulesFs.dryRun	Log intended FS writes without applying

How to use

1. ML Pulse: Open Modules File System (or Show Module for a single URI).
2. Leave Modules FS write off unless you intentionally enable gated writes.
3. To auto-deploy while editing: set modules DB + root (and URI prefix if needed), enable marklogic.deployOnSave.enabled, then save a file under the root — status bar confirms the modules URI.
4. Or run ML Pulse: Deploy Current Module anytime for the active file.

---

TDE

What it does

Author and validate TDE templates, extract sample rows, insert into the schemas database, and verify via Optic/SQL — from the editor or TDE Studio.

Configure

Setting / field	Purpose
Connection Form → Schemas DB (TDE) / marklogic.schemasDb	Optional target for template-insert; empty uses the content DB’s associated schemas DB
Template vars ML Pulse_TEST_URI / ML Pulse_TEST_FILE	Prefill sample document for extract (Studio and Extract command)

How to use

1. Open a TDE JSON/XML template → Validate TDE Template (Problems + Results on failure).
2. Extract Data Via TDE — uses test vars or prompts for URI / local file.
3. Open TDE Studio — Validate · Extract · Insert · Verify Optic / Verify SQL in one panel.
4. Snippets: ml-tde-json / ml-tde-xml; Outline lists context, views, and columns.

---

marklogic-unit-test

What it does

Runs a marklogic-unit-test module against the configured test endpoint.

Configure

• Test port / path settings as exposed in Settings / Connection Form for your environment.

How to use

1. Open a unit-test module → ML Pulse: Run marklogic-unit-test Module.
2. Inspect Results / Problems for pass/fail output.

---

Exploration tools

Command	Use
Peek MarkLogic Document	Inspect a document URI
Open Search Playground	CTS / search experiments
Explain Active Query	Server explain/plan
Show SPARQL Graph	Graph sketch for SPARQL
Show Request Timeline	Recent request timeline
Run Slow Query Radar	Spot slow requests
Refresh Forest Watch	Forest health glance
Save / Replay Query Fixture	Capture and replay eval fixtures

---

Notebooks

Open or create a .mlnb MarkLogic notebook and run cells against the active connection (same auth as eval).

---

Server explorer & status

• Activity bar MarkLogic Pulse icon → Server Configuration tree, Results, debug status.
• Refresh Server Configuration / Refresh Debug Status from the Command Palette.
• Status bar shows connection / host cues when configured.

---

File icon theme

1. Command Palette → File Icon Theme.
2. Choose MarkLogic Pulse.
3. Confirm distinct icons for .xqy / .sjs / .sql (and related) in the Explorer.

---

Keybindings

Action	Windows / Linux	macOS
Eval (XQuery / .sjs / SQL / SPARQL / GraphQL)	Ctrl+Alt+Enter	Cmd+Alt+Enter
Submit Optic (JSON)	Ctrl+Alt+Shift+Enter	Cmd+Alt+Shift+Enter
Show query results history	Ctrl+Alt+H	Cmd+Alt+H
Copy query results	Ctrl+Alt+Shift+C	Cmd+Alt+Shift+C
Export query results	Ctrl+Alt+Shift+S	Cmd+Alt+Shift+S

---

Settings reference

Prefer the Connection Form for host, ports, auth, DBs, and Modules URI prefix. Workspace-only paths can stay in Settings.

Setting	Purpose
marklogic.host	Hostname
marklogic.port / restBasePath	REST app server
marklogic.managePort / manageBasePath	Manage app server
marklogic.adminPort / adminBasePath	Admin app server
marklogic.documentsDb / modulesDb	Content and modules databases
marklogic.modulesRootDir	On-disk modules root for import / static-check / deploy-on-save URI rewrite
marklogic.modulesUriPrefix	Deploy URI prefix (also on Connection Form / profile)
marklogic.deployOnSave.enabled	Deploy saved modules under the root to the modules DB (off by default)
marklogic.authType	DIGEST, BASIC, or CLOUD
marklogic.ssl / rejectUnauthorized / pathToCa	TLS options
marklogic.resultsInEditorTab	Results in editor tab
marklogic.lint.enabled / strictStyle	Local XQuery/SJS diagnostics and house style
marklogic.lint.serverValidate	MarkLogic static-check on save/idle
marklogic.lint.serverValidateOnIdleMs	Idle debounce (ms)
marklogic.format.formatOnSave	Format .sjs on save
marklogic.modulesFs.writeEnabled / dryRun	Modules FS write gate

---

Language support summary

Language	Intelligence	Eval
XQuery (xquery-ml)	Completions, Outline, Go to Def / Refs / Rename, Extract / Inline / Organize Imports, Hover, Signature Help, lint, format, static-check	Yes
JavaScript / .sjs	Completions, Outline, Go to Def / Refs / Rename, Extract / Inline / Organize Requires, Hover, Signature Help, lint, format, static-check, CodeLens	Yes
SQL	Keywords, catalog, CTE/table nav, Rename	Yes
SPARQL	Keywords + snippets, Outline, Go to Def / Refs / Rename	Yes
Optic	Catalog fromView / op:from-view, method hints, Rename views/cols, Rows eval / Explain	Yes
GraphQL	Keywords, Outline, Go to Def / Refs / Rename	Yes
TDE (JSON/XML)	Outline, Go to Def / Refs / Rename (schema/view/column)	—

---

Author & links

• Report issues: marklogictools/ml-pulse-vscode-issues (new issue)
• Website: https://shivlingpulse.com/
• LinkedIn: Shivling Bhandare

License

Apache-2.0 and MIT. See NOTICE.txt and LICENSE.