Documents
Documents are the searchable, serialized objects within your indexes. As noted above, documents may be assigned a type, allowing separation of schema, while still maintaining searchability across all documents in the index. Within an index, each document is referenced by an _id value. This _id may be set manually ( document.setId() ) or, if not provided will be auto-generated when the record is persisted. Note that, if using numeric primary keys for your _id value, they will be cast as strings on serialization.

Creating a Document

The Document model is the primary object for creating and working with Documents. Let's say, again, we were going to create a book typed document in our index. We would do so, by first creating a Document object.
1
var book = getInstance( "[email protected]" ).new(
2
index = "bookshop",
3
type = "book",
4
properties = {
5
"title" = "Elasticsearch for Coldbox",
6
"summary" = "A great book on using Elasticsearch with the Coldbox framework",
7
"description" = "A long descriptio with examples on why this book is great",
8
"author" = {
9
"id" = 1,
10
"firstName" = "Jon",
11
"lastName" = "Clausen"
12
},
13
// date with specific format type
14
"publishDate" = dateTimeFormat( now(), "yyyy-mm-dd'T'hh:nn:ssZZ" ),
15
"edition" = 1,
16
"ISBN" = 123456789054321
17
}
18
);
19
20
book.save();
Copied!
In addition to population during the new method, we could also populate the document schema using other methods:
1
document.populate( myBookStruct )
Copied!
or by individual setters:
1
document.setValue(
2
"author",
3
{
4
"firstName" = "Jon",
5
"lastName" = "Clausen"
6
}
7
);
Copied!
If we want to manually assign the _id value, we would need to explicitly call setId( myCustomId ) to do so, or would need to provide an _id key in the struct provided to the new() or populate() methods.

Retrieving documents

To retrieve an existing document, we must first know the _id value. We can either retrieve using the Document object or by interfacing with the Client object directly. In either case, the result returned is a Document object, i f found, or null if not found.
Using the Document object's accessors:
1
var existingDocument = getInstance( "[email protected]" )
2
.setIndex( "bookshop" )
3
.setType( "book" )
4
.setId( bookId )
5
.get();
Copied!
Calling the get() method with explicit arguments:
1
var existingDocument = getInstance( "[email protected]" )
2
.get(
3
id = bookId,
4
index = "bookshop",
5
type = "book"
6
);
Copied!
Calling directly, using the same arguments, from the client:
1
var existingDocument = getInstance( "[email protected]" )
2
.get(
3
id = bookId,
4
index = "bookshop",
5
type = "book"
6
);
Copied!

Updating a Document

Once we've retrieved an existing document, we can simply update items through the Document instance and re-save them.
1
existingDocument.populate( properties = myUpdatedBookStruct ).save()
Copied!
You can also pass Document objects to the Client's save() method:
1
getInstance( "[email protected]" ).save( existingDocument );
Copied!

Updating individual fields in a document

The patch method of the Client allows a user to update select fields, bypassing the need for a fully retrieved document. This is similar to an UPDATE foo SET bar = 'xyz' WHERE id = :id query on a relational database. The method requires an index name, identifier and a struct containing the keys to be updated:
1
getInstance( "[email protected]" ).patch(
2
"bookshop",
3
bookId,
4
{
5
"title" : "My Book Title - 1st Edition"
6
}
7
);
Copied!
Nested keys can also be updated using dot-notation:
1
getInstance( "[email protected]" ).patch(
2
"bookshop",
3
bookId,
4
{
5
"author.firstName" : "Jonathan"
6
}
7
);
Copied!

Processing Bulk Operations

Elasticsearch allows to you perform bulk operations, which allows a developer to queue multiple backend operations on the search indices and send them all at once. The processBulkOperation method allows you to send a payload of operations in one batch. Note that create, update, and index actions require a source key, where as delete methods only require an operation key. The schema of the source key follows the same schema's described in the Bulk API Documentation:
1
var ops = [
2
{
3
"operation" : { "update" : { "_index" : "bookshop", "_id" : "xyz" } },
4
"source" : {
5
"doc" : { "title" : "My Book Title - 1st Edition" }
6
}
7
},
8
{
9
"operation" : { "delete" : { "_index" : "otherindex", "_id" : "abc" } }
10
},
11
{
12
"operation" : { "update" : { "_index" : "bookshop", "_id" : "efg" } }
13
"source" : {
14
"doc" : {
15
"title" = "Elasticsearch for Coldbox - 2nd Edition",
16
"summary" = "A new version of the original great book on using Elasticsearch with the Coldbox framework",
17
"description" = "A long description with examples on why this book is great",
18
"author" = {
19
"id" = 1,
20
"firstName" = "Jon",
21
"lastName" = "Clausen"
22
},
23
// date with specific format type
24
"publishDate" = dateTimeFormat( now(), "yyyy-mm-dd'T'hh:nn:ssZZ" ),
25
"edition" = 1,
26
"ISBN" = 123456789054321
27
},
28
"doc_as_upsert" : true
29
}
30
}
31
];
32
33
getInstance( "[email protected]" ).processBulkOperation( ops, { "refresh" : true } );
Copied!

Bulk Saving of Documents

Builk inserts and updates can be peformed by passing an array of Document objects to the Client's saveAll() method:
1
var documents = [];
2
3
for( var myStruct in myArray ){
4
var document = getInstance( "[email protected]" ).new(
5
index = myIndex,
6
type = myType,
7
properties = myStruct
8
);
9
10
arrayAppend( documents, document );
11
}
12
13
getInstance( "[email protected]" ).saveAll( documents );
Copied!

Update by Query

For advanced updates to documents in the index, the updateByQuery method can provide a powerful way to make bulk transformations on documents in your index. The updateByQuery method requires the passing of a "script" argument, which is a struct containing two strings - the language and the script. Elasticsearch supports a number of languages however, most of the time, the "painless" language is the easiest choice.
Let's say, for example, that you need to add a new key, with a default value, to every document in your index where the key does not already exist:
1
var searchBuilder = getInstance( "[email protected]" )
2
.mustNotExist( "isInPrint" );
3
getInstance( "[email protected]" )
4
.updateByQuery(
5
searchBuilder,
6
{
7
"script" : "ctx._source.isInPrint = true",
8
"lang" : "painless"
9
}
10
);
Copied!
In the above case, we queried for a lack of existence on the isInPrint key and created all documents which matched to use a default value of false.
Note the variable ctx._source used in the script, which is a reference to the document being iterated in the update loop. More information on crafting complex, scripted, query-based updates can be found in the official elasticsearch documentation.

Deleting a Document

Deleting documents is similar to the process of saving. The Document object may be used to delete a single item.
1
var document = getInstance( "[email protected]" )
2
.get(
3
id = documentId,
4
index = "bookshop",
5
type = books
6
);
7
if( !isNull( document ) ){
8
document.delete();
9
}
Copied!
Documents may also be deleted by passing a Document instance to the client:
1
getInstance( "[email protected]" ).delete( myDocument );
Copied!
Finally, documents may also be deleted by query, using the SearchBuilder ( more below ):
1
getInstance( "[email protected]" )
2
.new( index="bookshop", type="books" )
3
.match( "name", "Elasticsearch for Coldbox" )
4
.deleteAll();
Copied!

Parameters

The search builder also supports the addition of URL parameters, which may be used to transform or modify the behavior of bulk document actions. Comprehensive lists of these parameters may be found at the official Elasticsearch docs:
Of note are the throttling parameters, which are useful in dealing with large documents and/or indices. By default elasticsearch processes batch operations in groups of 1000 documents. Depending on the size of your documents and the collection, it may be preferable to throttle the batch to a smaller number of documents per batch:
1
getInstance( "[email protected]" )
2
.new( index="bookshop", type="books" )
3
.match( "name", "Elasticsearch for Coldbox" )
4
.param( "scroll_size", 100 )
5
.deleteAll();
Copied!
or

Asynchronous Bulk Operations

Both the updateByQuery and deleteByQuery methods support a waitForCompletion argument. By default, this is set to true. When passed as false, however, the method will return a Task instance, which can be used to follow up on the completion status of the action process. Note: You may also provide this argument in the SearchBuilder Params ( see "Parameters" above ): searchBuilder.param( 'wait_for_completion', false ), in lieu of providing the argument to the action. The end result is the same.
Last modified 9mo ago