Specifying transform as object gives error

[malteseduck]

The documentation here:

http://docs.marklogic.com/guide/node-dev/documents#id_76998

Shows that a transform can be specified as an object so that the transform params can be passed:

db.documents.write({
documents: [
{uri: '/doc/example1.json', content: {...}},
{uri: '/doc/example2.json', content: {...}}
],
transform: {
name: 'my-transform',
my-first-param: 'value',
my-second-param: 42
}
});

When I run something like this, though, I get this error:

RESTAPI-INVALIDREQ: (err:FOER0000) Invalid request: reason: Extension [object Object] does not exist.

Looking at the the node client documentation it shows the transform property can only be a string:

http://docs.marklogic.com/jsdoc/documents.html#write

so that would make sense. Should I be able to pass an object? Which documentation is lying?

This is against a MarkLogic 8.0-5.2 server. Is the client sending it incorrectly, or is the server parsing it incorrectly, or is something else wrong?

If I don't need to pass any parameters and just specify the string then it works fine.

[kcoleman-marklogic]

I would say none of the documentation is currently correct.

Which is to say, yes, you can just provide a string (the name), as you surmised. However, I think you can also provide an array (not an object) of the form [name, param1, param2, ..., paramN].

Edit: Or maybe that's [name, {param1:value1, ...}]. I confess I'm having problems making sense of the spec atm, which is probably why it's wrong on docs.marklogic.com. :-/

[ehennum]

I think the Node.js API needs to be able to provide named parameters to a transform. Mike, could you investigate?

[wooldridge]

Will take a look at this issue, thanks!

[malteseduck]

This seems to work:

db.documents.write({
transform: ['json-references', { type: 'normalize'} ],
documents: [...]
});

I guess it takes an array, but the params are passed as an object. I found this documentation:

http://docs.marklogic.com/guide/node-dev/extensions#id_27240

Which shows this. I guess I should have dug deeper. The other two parts of the documentation are still wrong, though. :) At least the functionality exists, and it is mostly consistent with qb.transform() for using the transforms in queries. The only "odd" thing is that it has to be an array.

Thanks.

[ehennum]

Great that you puzzled that out. It reminds me that the rationale behind the array was to ensure that the transform name could not collide with the names of the transform parameters.

The JSDoc seems like the weak link here.

[wooldridge]

To confirm, I created some working examples here:

https://github.com/wooldridge/ml-transform

We need to update documentation. @kcoleman-marklogic can you review this?

ON DOCS.MARKLOGIC.COM

http://docs.marklogic.com/guide/node-dev/documents#id_76998

Text:

"To apply a transform when creating or updating documents, call documents.write with a call object that includes the transform property. The transform property takes as its value an array of the transform name and an optional object of any parameter values the transformation expects."

Two examples:

db.documents.write({
  documents: [
    {uri: '/doc/example1.json', content: {...}},
    {uri: '/doc/example2.json', content: {...}}
  ],
  transform: [
    'my-transform',
    {
      my-first-param: 'value',
      my-second-param: 42
    }
  ]
});

db.documents.write({
  uri: '/doc/example1.json',
  content: {...}},
  transform: [
    'my-transform',
    {
      my-first-param: 'value',
      my-second-param: 42
    }
  ]
});

IN THE API DOCS

http://docs.marklogic.com/jsdoc/documents.html#write

@param {string|mixed[]} [transform] - the name of a transform extension to apply to each document or an array including the name of the transform extension and an object of parameter values; the transform must have been installed using the {@link transforms#write} function.