Connecting to CSS to Implement Distributed Search in Applications

Prerequisites

Perform the following operations to obtain the URL for CSS to provide services:

1. Log in to the CSS management console.
2. In the navigation tree on the left, click Cluster Management.
3. In the cluster list, obtain the value of the private network address.

Creating a CSS Connector

1. Log in to the application designer by referring to Logging In to the Application Designer.
2. In the navigation pane, choose Integrations.
3. Click Connector Instance under Connector.
4. In the navigation pane, choose Data > Elastic Search.
5. In the right pane, click + and set the parameters.
   Figure 1 Creating an Elastic Search instance
   

   Table 1 Parameters for creating a CSS connector

   Parameter	Description
   Name	Name of the connector to be created. The naming requirements are as follows: The value cannot exceed 64 characters, including the prefix namespace. To prevent duplicate data names among different tenants, each tenant must define a unique namespace when first creating an application. A tenant can create only one namespace. After being created, the namespace cannot be modified. Start with a letter and can contain only letters, digits, and underscores (_). Do not end with an underscore (_).
   Addresses	Private network address for accessing the CSS service. Set this parameter to the value obtained from Prerequisites.
   Version	Major version of Elasticsearch. Only versions 6 and 7 are supported.
   Security Mode	When you access a cluster in security mode, communication encryption and security authentication are performed. In security mode, if no protocol is specified for the address, HTTPS is used by default.
   Username	Account name for logging in to CSS. This parameter is displayed only when Security Mode is enabled.
   Password	Password of the account for logging in to CSS. This parameter is displayed only when Security Mode is enabled.
   Use Certificate	The custom certificate will be used only when the HTTPS protocol is used and the certificate verification fails.
   Certificate	The certificate is used to construct a client to verify the authenticity of the server. Only a certificate in x509 format is supported. This parameter is displayed only when Use Certificate is selected.
   Client Certificate	This certificate is used by the server to verify the client. Currently, the certificate in x509 format is supported. This parameter is displayed only when Use Certificate is selected.
   Client Certificate Key	This key is used to decrypt the client certificate. This parameter is displayed only when Use Certificate is selected.
   Package Current Configuration	If this parameter is selected, the connector will be packed together with applications. For example, if an application package is released to the runtime environment, the current configuration is synchronized to the runtime environment by default. If this option is not selected, the connector will not be packaged and released to the runtime environment. In this case, you need to create the corresponding connector by referring to Managing Connectors in Applications. This parameter is selected by default. You are advised not to select this option in information-sensitive scenarios.
   Adding tenant identification to the index	When enabled, the names and aliases of the generated indexes will automatically include a tenant prefix (e.g., Tenant identifier--Name/Alias).

6. Click the save button.

Calling a Connector in a Script

In an event, a connector is called to connect to CSS.

1. Create an empty script by referring to Creating a Blank Script.
2. In the script editor, enter the following code to call a CSS connector and implement index operations:

   //Import the standard library file on which the event depends. ES is the standard library preset in the system.
   import * as es from 'es'
   
   /
      Example of calling some event APIs of the ES module
   */
   
   let indexName1 = "indexName1"
   let indexName2 = "indexName2"
   let aliasName = "alias"
   
   let client = es.newClient('CSS1') //Enter the connector instance name when creating a client. CSS1 is used as an example.
   
   //1. Prepare. If an index already exists, delete it first. (Deleting the index will also delete the documents in the index.)
   let exist = client.checkIndexExist(indexName1)
   if (exist) { client.dropIndex(indexName1) }
   exist = client.checkIndexExist(indexName2)
   if (exist) { client.dropIndex(indexName2) }
   client.createIndex(indexName1) //Create an index without a mapping (dynamically generate a mapping based on the inserted document).
   
   //2. Insert or update a document. If a document with the same ID already exists, update the document. If no document with the same ID exists, insert the document.
   let doc = {
       "_id": "1001," //Custom document ID. If _id is not specified, a unique random document ID is automatically generated.
       "foo": "apple",
       "bar": 30,
   }
   let docID = client.indexDoc(indexName1, doc) //Return the document ID of the index.
   console.log("docID:", docID) //The docID is 1001.
   
   //3. Insert or update documents in batches.
   let docs = [    //Define two more documents.
       {
           "_id": "1002",
           "foo": "banana",
           "bar": 40,
       },
       {
           "_id": "1003",
           "foo": "orange",
           "bar": 50,
           "baz": true,
       }
   ]
   client.bulkIndexDocs(indexName1, docs)
   
   //4. Partially update the document.
   client.updateDocByDocID(indexName1, "1001", {
       bar: 35, //Partially updated. Only the bar field is changed to 35.
       qux: "none",    //Add a new field and value.
   })
   
   //5. After the addition, deletion, or modification, the refresh function can be explicitly called to refresh the page. Otherwise, the page can be searched only after about 1 second.
   client.refresh(indexName1)
   
   //6. Query the number of records.
   let count = client.countDocs(indexName1)
   console.log("count:", count) //3 should be printed.
   
   //7. Query by condition.
   let condition = { 
       query: {
           range: {
               bar: { gte: 40 }
           }
       }
   }
   let searchRes = client.search(condition, indexName1) //Query the documents whose bar field is greater than 40.
   console.log("searchRes: ", searchRes)   //Two matching documents are printed.
   
   //8. Update by condition.
   let script = 'ctx._source.bar = 70' 
   let query = {
       match: {
           foo: "apple",
       }
   }
   let updatedCount = client.updateByQuery(indexName1, query, script) //Updates in batches. Change the bar of the documents whose foo is apple to 70.
   console.log("updatedCount:", updatedCount) //Print the number of modified documents. Here, 1 is printed.
   client.refresh(indexName1)
   
   //9. Query only the ID list.
   let idList = client.searchIDList(indexName1, {
       query: {
           match_all: {}   //Query all records.
       },
       size: 5  //A maximum of five results can be found.
   })
   console.log("idList:", idList) //The ["1001","1002","1003"] is printed.
   
   //10. Lightweight query (Compared with the search function, the query function does not require JSON conditions and requires only simple character strings.)
   let queryRes = client.query("foo:apple", false, indexName1) //Query the documents whose foo field is apple. The second parameter false indicates that only the first 10 documents are queried. The value true indicates that all documents are queried.
   console.log("queryRes1:", queryRes) //One query result is displayed.
   queryRes = client.query("foo:apple OR banana", false, indexName1) //Except the document whose foo field is apple, add the full-text query result of banana.
   console.log("queryRes2:", queryRes) //Two query results are displayed.
   
   //11. Create the second index and customize the mapping.
   let mp = {
       dynamic: "strict",
       properties: {
           name: { type: "text"    },
           age: {  type: "integer" }
       }
   }
   client.createIndexWithMapping(indexName2, mp)
   
   //12. Obtain the index mapping.
   let mpRes = client.getMapping(indexName2)
   console.log("mapping: ", mpRes)    //Print the mapping.
   
   //13. Bind an alias.
   client.attachAlias(indexName1, aliasName)
   
   //14. The alias operation is the same as the index operation.
   client.deleteDocByDocID(aliasName, "1001")
   client.refresh(aliasName)
   count = client.countDocs(aliasName)
   console.log("countAfterDelete:", count) //2 is displayed here.
   
   //15. Obtain the index associated with the alias.
   let attached = client.getAttachedIndexes(aliasName)
   console.log(attached)   //indexName1 is printed.
   
   //16. Obtain the alias of index management.
   let ali = client.getAlias(indexName1)
   console.log(ali)    //Print the alias name.
   
   //17. Bind the new index and unbind the old index.
   client.attachAndDetachAlias(indexName2, indexName1, aliasName)
   attached = client.getAttachedIndexes(aliasName)
   console.log(attached)   //Print indexName2.
   
   //18. Obtain the basic information (alias and number of documents) about all indexes.
   let catRes = client.cat()
   console.log("catRes: ", catRes)

   In es.newClient('Namespace__CSS1'), Namespace __CSS1 is the connector name.

3. Click in the upper part of the script editor to save the script.
4. Click to execute the script.
5. Click in the upper right corner of the test window without setting input parameters.
6. On the log tab page, you can view that the index is created.

   0826 10:20:14.685|debug|vm[86]>>> AstroZero 1.2.8 - Production on 2019-08-23 14:44:06 2ce004a222b087e3ac55c70d4e2482d7338d81aa debug (<unknown>.ts:0)
   0826 10:20:14.685|debug|vm[86]>>> script: Test_CSS1 1.0.1  (<unknown>.ts:0)
   0826 10:20:14.685|debug|vm[86]>>> locale: zh_CN (<unknown>.ts:0)
   0826 10:20:14.685|debug|vm[86]>>> timezone: (GMT+00:00) Greenwich Mean Time (GMT) (<unknown>.ts:0)
   0826 10:20:14.766|debug|vm[86]>>> docID:  1001 (Test_CSS1.ts:28)
   0826 10:20:14.812|debug|vm[86]>>> count:  3 (Test_CSS1.ts:57)
   0826 10:20:14.815|debug|vm[86]>>> searchRes:  {
       "aggregations": {},
       "hits": [
           {
               "_id": "1002",
               "_index": "indexname1",
               "_score": 1,
               "_source": {
                   "bar": 40,
                   "foo": "banana"
               },
               "_type": "_doc"
           },
           {
               "_id": "1003",
               "_index": "indexname1",
               "_score": 1,
               "_source": {
                   "bar": 50,
                   "baz": true,
                   "foo": "orange"
               },
               "_type": "_doc"
           }
       ],
       "max_score": 1,
       "total": {
           "relation": "eq",
           "value": 2
       }
   } (Test_CSS1.ts:68)
   0826 10:20:14.82|debug|vm[86]>>> updatedCount:  1 (Test_CSS1.ts:78)
   0826 10:20:14.831|debug|vm[86]>>> idList:  [
       "1002",
       "1003",
       "1001"
   ] (Test_CSS1.ts:88)
   0826 10:20:14.833|debug|vm[86]>>> queryRes1:  {
       "_id": "1001",
       "_index": "indexname1",
       "bar": 70,
       "foo": "apple",
       "qux": "none"
   } (Test_CSS1.ts:92)
   0826 10:20:14.835|debug|vm[86]>>> queryRes2:  {
       "_id": "1002",
       "_index": "indexname1",
       "bar": 40,
       "foo": "banana"
   },
   {
       "_id": "1001",
       "_index": "indexname1",
       "bar": 70,
       "foo": "apple",
       "qux": "none"
   } (Test_CSS1.ts:94)
   0826 10:20:14.879|debug|vm[86]>>> mapping:  {
       "age": {
           "type": "integer"
       },
       "name": {
           "type": "text"
       }
   } (Test_CSS1.ts:108)
   0826 10:20:14.898|debug|vm[86]>>> countAfterDelete:  2 (Test_CSS1.ts:117)
   0826 10:20:14.899|debug|vm[86]>>> indexname1 (Test_CSS1.ts:121)
   0826 10:20:14.899|debug|vm[86]>>> alias (Test_CSS1.ts:125)
   0826 10:20:14.908|debug|vm[86]>>> indexname2 (Test_CSS1.ts:130)
   0826 10:20:14.912|debug|vm[86]>>> catRes:  [
       {
           "indexName": "indexname1",
           "aliases": null,
           "docCount": 2
       },
       {
           "indexName": "indexname2",
           "aliases": [
               "alias"
           ],
           "docCount": 0
       }
   ] (Test_CSS1.ts:134)