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.
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
- Install MarkLogic Pulse from the Marketplace, or Install from VSIX… with a built
ml-pulse-x.y.z.vsix.
- Run Developer: Reload Window after install or upgrade.
Getting started
- Command Palette → ML Pulse: Open Connection Form.
- Enter host, REST port, username, password (and optional documents/modules DB, SSL, Modules URI prefix).
- Save & Activate, then Test.
- 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
Connection & security
What it does
Named connection profiles, a Connection Form UI, Connection Doctor, and passwords stored in VS Code SecretStorage (not plaintext settings).
- 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.
- ML Pulse: Save Current Connection as Profile — named entry under
marklogic.profiles.
- ML Pulse: Set MarkLogic Password / Clear Stored Password — SecretStorage for the active profile.
- ML Pulse: Switch Connection Profile / Rename / Delete.
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 and softens XDMP-MODNOTFOUND when the file exists on disk but the DB URI needs the prefix.
How to use
- Open Connection Form → fill values → Save & Activate → Test.
- Switch profiles from the Command Palette when jumping between environments.
- 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.
| 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
- Open a query file (or select a fragment) → Ctrl+Alt+Enter (language-aware eval) or the matching ML Pulse: Eval … command.
- Optic JSON: Ctrl+Alt+Shift+Enter, or Command Palette CSV / XML variants.
- View ML Pulse → Results; use Copy (
Ctrl+Alt+Shift+C), Export (Ctrl+Alt+Shift+S), Clear, Focus.
- 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.
| 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
- Open a workspace with modules (e.g. repo
test-app) and wait briefly for indexes.
- Type
hw: / hw:hel after an import module → accept a function → Tab through required args only.
- F12 / Ctrl+Click calls,
$vars, and import … at "…" paths.
- Shift+F12 / reference CodeLens for workspace uses.
- Lightbulb on
ml-pulse Problems → Quick Fix / Fix All; on compile errors → Copy / Explain.
- 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.
- 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
const lib = require('/javascript/library') then type lib. → accept hello(friend) with tabstops.- F12 on
hello( or the require path.
- Format Document / save as configured; Fix All for safe lint edits.
SQL / SPARQL / Optic / GraphQL
What it does
Keyword/snippet completions; SQL catalog refresh and CTE/table navigation; Optic method hints in .sjs plus Rows API eval; GraphQL submit; SPARQL eval and optional graph sketch.
- Active connection for live SQL catalog / eval.
- ML Pulse: Refresh SQL Catalog after schema changes.
How to use
.sql → eval; Refresh SQL Catalog → complete/jump table names..rq / .sparql → Eval SPARQL; Show SPARQL Graph when exploring.- Optic buffer → Submit JSON/CSV/XML.
.graphql / .gql → Submit GraphQL Query.
Debugging
What it does
Interactive JS and XQuery debug: connect a debug server, then launch (evaluate current module) or attach to an in-flight request.
- MarkLogic 10.0-4+ for JS debug.
- 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
- Connect the matching debug server.
- Set breakpoints → start a launch or attach config from the Run and Debug view.
- Disconnect … Debug Server when finished. See installation/debug docs under
docs/ for deeper setup.
Modules browser
What it does
Browse MarkLogic modules via a virtual file system; optional gated write (confirm + dry-run).
| Setting |
Purpose |
marklogic.modulesFs.writeEnabled |
Allow writes through the modules FS |
marklogic.modulesFs.dryRun |
Log intended writes without applying |
How to use
- ML Pulse: Open Modules File System (or Show Module for a single URI).
- Leave write off unless you intentionally enable gated writes.
TDE
What it does
Validate templates, extract sample data via TDE, and open TDE Studio.
How to use
- Open a TDE template → Validate TDE Template.
- Extract Data Via TDE against sample content.
- Open TDE Studio for a guided UI.
marklogic-unit-test
What it does
Runs a marklogic-unit-test module against the configured test endpoint.
- Test port / path settings as exposed in Settings / Connection Form for your environment.
How to use
- Open a unit-test module → ML Pulse: Run marklogic-unit-test Module.
- Inspect Results / Problems for pass/fail output.
| 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
- Command Palette → File Icon Theme.
- Choose MarkLogic Pulse.
- 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 URI rewrite |
marklogic.modulesUriPrefix |
Deploy URI prefix (also on Connection Form / profile) |
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, Hover, lint, format, static-check |
Yes |
JavaScript / .sjs |
Completions, hover, lint, format, nav / CodeLens |
Yes |
| SQL |
Keywords, catalog, CTE/table nav |
Yes |
| SPARQL |
Keywords + snippets |
Yes |
| Optic |
Method hints in .sjs + Rows eval |
Yes |
| GraphQL |
Keywords |
Yes |
Author & links
License
Apache-2.0 and MIT. See NOTICE.txt and LICENSE.
