Curl Node Java

Retrieve and Rank

API Reference

Introduction

API Reference pages provide an easy way for you to see the methods that are provided by a service and how to call them. This column provides general information and explains the parameters that are required by methods when called from different languages. Its content changes based on the selected language. On screens that are wide enough, the right column provides selectable tabs that show how to make sample method calls in REST (by using the cURL command), Node.js, and Java, and includes example responses to those calls. On narrow screens, these examples are inlined, and you can access the page navigation and switch between REST, Node.js, and Java examples from the menu at upper left.

API Endpoint

https://gateway.watsonplatform.net/retrieve-and-rank/api

Node

npm install watson-developer-cloud

The code examples on this tab use the client-side library that is provided for Java, rather than issuing REST calls.

Important: You must import both the IBM Watson-specific Java SDK and version 5.5.1 of Apache SolrJ (solr-solrj-5.5.1.jar) into your Java projects for the Retrieve and Rank service. You can download the Apache SolrJ package from http://www.apache.org/dyn/closer.lua/lucene/solr/5.5.1.

Important: To use the Java SDK for the Retrieve and Rank service, you must understand how to program in the common SolrJ API as well as in the IBM Watson-specific Java SDK. For information on using SolrJ, see the SolrJ 5.5.1 API specification.

Maven

<dependency>
  <groupId>org.apache.solr:solr-solrj</groupId>
  <artifactId>java-wrapper</artifactId>
  <version>5.5.1</version>
</dependency>

<dependency>
  <groupId>com.ibm.watson.developer_cloud</groupId>
  <artifactId>java-wrapper</artifactId>
  <version>3.4.1</version>
</dependency>

Gradle

compile 'org.apache.solr:solr-solrj:5.5.1'
compile 'com.ibm.watson.developer_cloud:java-sdk:3.4.1'

More information

An interactive tool for testing calls to the API and viewing live responses from the service is available in the Retrieve and Rank API explorer.

Descriptions of Node classes listed in this reference are available in the Node documentation for the Watson Developer Cloud Node.js SDK.

Descriptions of Java classes listed in this reference are available in the Javadoc for the Watson Developer Cloud Java SDK.

Authentication

You authenticate to the Retrieve and Rank API by providing the username and password that are provided in the service credentials for the service instance that you want to use. The API uses basic authentication.

After you create an instance of the Retrieve and Rank service, you can view the username and password by selecting Service Credentials from the left pane of the service dashboard.

Replace {username} and {password} with your service credentials

var watson = require('watson-developer-cloud');
var retrieve_and_rank = watson.retrieve_and_rank({
  username: '{username}',
  password: '{password}',
  version: 'v1'
});
RetrieveAndRank service = new RetrieveAndRank();
service.setUsernameAndPassword("{username}","{password}");

Methods

Create Solr cluster

Provisions a Solr cluster asynchronously. When the operation is successful, the status of the cluster is set to NOT_AVAILABLE. The status must be READY before you can use the cluster.

POST /v1/solr_clusters

Request

Parameter Type Description
cluster_size Body Size of the cluster to create. Ranges from 1 to 7. Send an empty value to create a small free cluster for testing. You can create only one free cluster. For information about cluster sizing, see Sizing your Retrieve and Rank cluster.
cluster_name Body Name to identify the cluster.

Example request

curl -H "Content-Type: application/json" -X POST -u "{username}":"{password}" -d "{\"cluster_size\":\"1\",\"cluster_name\":\"My cluster\"}" "https://gateway.watsonplatform.net/retrieve-and-rank/api/v1/solr_clusters"
var watson = require('watson-developer-cloud');
var retrieve_and_rank = watson.retrieve_and_rank({
  username: '{username}',
  password: '{password}',
  version: 'v1'
});

retrieve_and_rank.createCluster({
  cluster_size: '1',
  cluster_name: 'My cluster'
},
  function (err, response) {
    if (err)
      console.log('error:', err);
    else
      console.log(JSON.stringify(response, null, 2));
});
RetrieveAndRank service = new RetrieveAndRank();
service.setUsernameAndPassword("{username}","{password}");

SolrClusterOptions options = new SolrClusterOptions("My cluster", 1);
SolrCluster cluster = service.createSolrCluster(options);
System.out.println("SolrCluster: " + cluster);

// wait until the cluster is available
while (cluster.getStatus() == Status.NOT_AVAILABLE) {
   Thread.sleep(10000); // sleep 10 seconds
   cluster = service.getSolrCluster(cluster.getId());
   System.out.println("SolrCluster status: " + cluster.getStatus());
   System.out.println("SolrCluster ID: " + cluster.getId());
   }

Response

Name Description
solr_cluster_id Unique identifier for this cluster.
cluster_name Name that identifies the cluster.
cluster_size Size of the cluster to create.
solr_cluster_status The state of the cluster: NOT_AVAILABLE or READY.

Example response

SolrCluster: My cluster
SolrCluster status: READY
SolrCluster ID: sc1ca23733_faa8_49ce_b3b6_dc3e193264c6
    
{
  "solr_cluster_id": "sc1ca23733_faa8_49ce_b3b6_dc3e193264c6",
  "cluster_name": "My cluster",
  "cluster_size": "1",
  "solr_cluster_status": "NOT_AVAILABLE"
}

List Solr clusters

Retrieves the list of Solr clusters for the service instance.

GET /v1/solr_clusters

Request

No arguments.

Example request

curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/retrieve-and-rank/api/v1/solr_clusters"
var watson = require('watson-developer-cloud');
var retrieve_and_rank = watson.retrieve_and_rank({
  username: '{username}',
  password: '{password}',
  version: 'v1'
});

retrieve_and_rank.listClusters({},
  function (err, response) {
    if (err)
      console.log('error:', err);
    else
      console.log(JSON.stringify(response, null, 2));
});
RetrieveAndRank service = new RetrieveAndRank();
service.setUsernameAndPassword("{username}","{password}");

SolrClusterList clusters = service.getSolrClusters();
System.out.println(clusters);

Response

Name Description
clusters An array of [clusters] that are available for the service instance.
clusters
Name Description
solr_cluster_id Unique identifier for this cluster.
cluster_name Name that identifies the cluster.
cluster_size Size of the cluster to create. Ranges from 1 - 7.
solr_cluster_status The state of the cluster: (NOT_AVAILABLE or READY).

Example response

{
  "clusters": [
    {
      "solr_cluster_id": "sc9e4b0eab_fc66_4439_a83a_a81fc6f1e81f",
      "cluster_name": "2nd cluster",
      "cluster_size": "",
      "solr_cluster_status": "NOT_AVAILABLE"
    },
    {
      "solr_cluster_id": "sc1ca23733_faa8_49ce_b3b6_dc3e193264c6",
      "cluster_name": "My cluster",
      "cluster_size": "1",
      "solr_cluster_status": "READY"
    }
  ]
}

Get information about a Solr cluster

Returns status and other information about a cluster.

GET /v1/solr_clusters/{solr_cluster_id}

Request

Parameter Type Description
solr_cluster_id String (Required) Unique identifier for this cluster.

Example request

curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/retrieve-and-rank/api/v1/solr_clusters/sc1ca23733_faa8_49ce_b3b6_dc3e193264c6"
var watson = require('watson-developer-cloud');
var retrieve_and_rank = watson.retrieve_and_rank({
  username: '{username}',
  password: '{password}',
  version: 'v1'
});

retrieve_and_rank.pollCluster({
  cluster_id: 'sc1ca23733_faa8_49ce_b3b6_dc3e193264c6'
},
  function (err, response) {
    if (err)
      console.log('error:', err);
    else
      console.log(JSON.stringify(response, null, 2));
});
RetrieveAndRank service = new RetrieveAndRank();
service.setUsernameAndPassword("{username}","{password}");

System.out.println(service.getSolrCluster("sc1ca23733_faa8_49ce_b3b6_dc3e193264c6"));

Response

Name Description
solr_cluster_id Unique identifier for this cluster.
cluster_name Name that identifies the cluster.
cluster_size Size of the cluster. Ranges from 1 - 7.
solr_cluster_status The state of the cluster: (NOT_AVAILABLE or READY).

Example response

{
  "solr_cluster_id": "sc1ca23733_faa8_49ce_b3b6_dc3e193264c6",
  "cluster_name": "My cluster",
  "cluster_size": "1",
  "solr_cluster_status": "READY"
}

Delete Solr cluster

Stops and deletes a Solr Cluster asynchronously.

DELETE /v1/solr_clusters/{solr_cluster_id}

Request

Parameter Type Description
solr_cluster_id Path (Required) ID of the cluster to delete.
Parameter Type Description
cluster_id String (Required) ID of the cluster to delete.

Example request

curl -X DELETE -u "{username}":"{password}" "https://gateway.watsonplatform.net/retrieve-and-rank/api/v1/solr_clusters/sc1ca23733_faa8_49ce_b3b6_dc3e193264c6"
var watson = require('watson-developer-cloud');
var retrieve_and_rank = watson.retrieve_and_rank({
  username: '{username}',
  password: '{password}',
  version: 'v1'
});

retrieve_and_rank.deleteCluster({
  cluster_id: 'sc369654e5_606d_48de_92cd_9f436f55c73f'
},
  function (err, response) {
    if (err)
      console.log('error:', err);
    else
      console.log(JSON.stringify(response, null, 2));
});
RetrieveAndRank service = new RetrieveAndRank();
service.setUsernameAndPassword("{username}","{password}");

service.deleteSolrCluster("sc1ca23733_faa8_49ce_b3b6_dc3e193264c6");

Response

HTTP response 200 (no object returned)

Upload Solr configuration

Uploads a zip file containing the configuration files for your Solr collection. The zip file must include schema.xml, solrconfig.xml, and other files you need for your configuration.

Configuration files on the zip file's path are not uploaded. The request fails if a configuration with the same name exists. To update an existing config, use the Solr configuration API.

POST /v1/solr_clusters/{solr_cluster_id}/config/{config_name}

Request

Parameter Type Description
Content-Type Header (Required) Media type of the configuration. Use "application/zip".
solr_cluster_id Path (Required) Cluster ID for the configuration.
config_name Path (Required) The name of the configuration to create.
body Body (Required) The compressed configuration files.
Parameter Data type Description
cluster_id string (Required) Cluster ID for the configuration.
config_name string (Required) The name of the configuration to create.
config_zip_path string (Required) The path to the zip files that contains configuration files.

Example request

curl -X POST -H "Content-Type: application/zip" -u "{username}":"{password}" "https://gateway.watsonplatform.net/retrieve-and-rank/api/v1/solr_clusters/sc1ca23733_faa8_49ce_b3b6_dc3e193264c6/config/example_config" --data-binary @/configs/example_config.zip
var watson = require('watson-developer-cloud');
var retrieve_and_rank = watson.retrieve_and_rank({
  username: '{username}',
  password: '{password}',
  version: 'v1'
});

var params = {
  cluster_id: 'sc1ca23733_faa8_49ce_b3b6_dc3e193264c6',
  config_name: 'example_config',
  config_zip_path: '/configs/example_config.zip'
};

retrieve_and_rank.uploadConfig(params,
  function (err, response) {
    if (err)
      console.log('error:', err);
    else
      console.log(JSON.stringify(response, null, 2));
});
RetrieveAndRank service = new RetrieveAndRank();
service.setUsernameAndPassword("{username}","{password}");

File configZip = new File("/configs/example_config.zip");
service.uploadSolrClusterConfigurationZip("sc1ca23733_faa8_49ce_b3b6_dc3e193264c6",
"example_config", configZip);

Response

HTTP response 200 (no object returned)

List Solr configurations

Retrieves all configurations for a cluster.

GET /v1/solr_clusters/{solr_cluster_id}/config/

Request

Parameter Type Description
solr_cluster_id Path (Required) ID of the cluster to query.
Parameter Data type Description
cluster_id string (Required) ID of the cluster to query.

Example request

curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/retrieve-and-rank/api/v1/solr_clusters/sc1ca23733_faa8_49ce_b3b6_dc3e193264c6/config"
var watson = require('watson-developer-cloud');
var retrieve_and_rank = watson.retrieve_and_rank({
  username: '{username}',
  password: '{password}',
  version: 'v1'
});

retrieve_and_rank.listConfigs({
  cluster_id: 'sc1ca23733_faa8_49ce_b3b6_dc3e193264c6'
},
  function (err, response) {
    if (err)
      console.log('error:', err);
    else
      console.log(JSON.stringify(response, null, 2));
});
RetrieveAndRank service = new RetrieveAndRank();
service.setUsernameAndPassword("{username}","{password}");

System.out.println(service.getSolrClusterConfigurations("sc1ca23733_faa8_49ce_b3b6_dc3e193264c6"));

Response

Name Description
solr_configs Array of configurations. Shows the value of config_name.

Example response

{
  "clusters": [
    {
      "solr_cluster_id": "scfaaf8903_02c1_4297_84c6_76b79537d849",
      "cluster_name": "test-cluster",
      "cluster_size": "1",
      "solr_cluster_status": "READY"
    }
  ]
}
[example_config]
{
  "created": "2016-02-02T13:27:47.927-0500",
  "ranker_id": "42B250x11-rank-431",
  "name": "My ranker",
  "status": "Training",
  "status_description": "The ranker instance is in its training phase, not yet ready to accept rank requests",
  "url": "https://gateway.watsonplatform.net/retrieve-and-rank/api/v1/rankers/42B250x11-rank-431"
}
{
  "rankers": [
    {
      "created": "2016-02-02T13:27:47.927-0500",
      "ranker_id": "42B250x11-rank-431",
      "name": "My ranker",
      "url": "https://gateway.watsonplatform.net/retrieve-and-rank/api/v1/rankers/42B250x11-rank-431"
    }
  ]
}
{
  "solr_configs": [
      "example_config"
  ]
}

Get configuration

Retrieves the configuration for a cluster by its name.

GET /v1/solr_clusters/{solr_cluster_id}/config/{config_name}

Request

Parameter Type Description
solr_cluster_id Path (Required) Cluster ID for the configuration.
config_name Path (Required) The name of the configuration to retrieve.
Parameter Data type Description
cluster_id string (Required) Cluster ID for the configuration.
config_name string (Required) The name of the configuration to retrieve.

Example request

curl -u "{username}":"{password}" -o example_config.zip "https://gateway.watsonplatform.net/retrieve-and-rank/api/v1/solr_clusters/sc1ca23733_faa8_49ce_b3b6_dc3e193264c6/config/example_config"
var watson = require('watson-developer-cloud');
var retrieve_and_rank = watson.retrieve_and_rank({
  username: '{username}',
  password: '{password}',
  version: 'v1'
});

var params = {
  cluster_id: 'sc1ca23733_faa8_49ce_b3b6_dc3e193264c6',
  config_name: 'example_config'
};

retrieve_and_rank.getConfig(params).pipe(fs.createWriteStream('config_example.zip'));
RetrieveAndRank service = new RetrieveAndRank();
service.setUsernameAndPassword("{username}","{password}");

Path FROM = service.getSolrClusterConfigurationZip("sc1ca23733_faa8_49ce_b3b6_dc3e193264c6", "example_config");
Path TO = Paths.get(".");
CopyOption[] options = new CopyOption[]{
  StandardCopyOption.REPLACE_EXISTING,
  StandardCopyOption.COPY_ATTRIBUTES
};
Files.copy(FROM, TO, options);

Response

Returns a .zip file (MIME type application/zip)

Example response

Download the blank_example_solr_config.zip file.

 % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 20596    0 20596    0     0  34838      0 --:--:-- --:--:-- --:--:-- 34790

Delete configuration

Deletes the configuration for a cluster.

DELETE /v1/solr_clusters/{solr_cluster_id}/config/{config_name}

Request

Parameter Type Description
solr_cluster_id Path (Required) Cluster ID for the configuration.
config_name Path (Required) The name of the configuration to delete.
Parameter Data type Description
cluster_id string (Required) Cluster ID for the configuration.
config_name string (Required) The name of the configuration to delete.

Example request


curl -X DELETE -u "{username}":"{password}" "https://gateway.watsonplatform.net/retrieve-and-rank/api/v1/solr_clusters/sc1ca23733_faa8_49ce_b3b6_dc3e193264c6/config/example_config"
var watson = require('watson-developer-cloud');
var retrieve_and_rank = watson.retrieve_and_rank({
  username: '{username}',
  password: '{password}',
  version: 'v1'
});

var params = {
  cluster_id: 'sc1ca23733_faa8_49ce_b3b6_dc3e193264c6',
  config_name: 'example_config'
};

retrieve_and_rank.deleteConfig(params,
  function (err, response) {
    if (err)
      console.log('error:', err);
    else
      console.log(JSON.stringify(response, null, 2));
});
RetrieveAndRank service = new RetrieveAndRank();
service.setUsernameAndPassword("{username}","{password}");

service.deleteSolrClusterConfiguration("sc1ca23733_faa8_49ce_b3b6_dc3e193264c6", "example_config");

Response

HTTP response 200

Create Solr collection

An example of a method that forwards to the Solr Collections API. This Retrieve and Rank resource improves error handling and resiliency of the Solr Collections API.

POST /v1/solr_clusters/{solr_cluster_id}/solr/admin/collections/

Request

Parameter Type Description
solr_cluster_id Form (Required) Cluster ID for the collection.
action Form (Required) Operation to carry out. Use "CREATE" in this method.
name Form (Required) The name of the collection to create.
collection.configName Form The name of the configuration to use. Default is the collection name.
wt Query Writer type. Default is standard (xml). Specifies which QueryResponseWriter to use to process the request. Valid values are declared in the solrconfig.xml file.
Parameter Data type Description
cluster_id string (Required) Cluster ID for the configuration.
config_name string (Required) The name of the configuration to create.
collection_name string (Required) The name of the collection to create.
wt string Writer type. Default is json. Specifies which QueryResponseWriter to use to process the request. Valid values are declared in the solrconfig.xml file.

Example request

curl -X POST -u "{username}":"{password}" "https://gateway.watsonplatform.net/retrieve-and-rank/api/v1/solr_clusters/sc1ca23733_faa8_49ce_b3b6_dc3e193264c6/solr/admin/collections" -d "action=CREATE&name=example_collection&collection.configName=example_config&wt=json"
var watson = require('watson-developer-cloud');
var retrieve_and_rank = watson.retrieve_and_rank({
  username: '{username}',
  password: '{password}',
  version: 'v1'
});

var params = {
  cluster_id: 'sc1ca23733_faa8_49ce_b3b6_dc3e193264c6',
  config_name: 'example_config',
  collection_name: 'example_collection',
  wt: 'json'
};

retrieve_and_rank.createCollection(params,
  function (err, response) {
    if (err)
      console.log('error:', err);
    else
      console.log(JSON.stringify(response, null, 2));
});
RetrieveAndRank service = new RetrieveAndRank();
service.setUsernameAndPassword("{username}","{password}");

CollectionAdminRequest.Create createCollectionRequest =
        new CollectionAdminRequest.Create();
createCollectionRequest.setCollectionName("example_collection");
createCollectionRequest.setConfigName("example_config");

System.out.println("Creating collection...");
CollectionAdminResponse response = createCollectionRequest.process(solrClient);
    if (!response.isSuccess()) {
      System.out.println(response.getErrorMessages());
      throw new IllegalStateException("Failed to create collection: "
          + response.getErrorMessages().toString());
    }
System.out.println("Collection created.");
System.out.println(response);
      

Response

For details about the response, see the Solr Collections API in the Apache Solr Reference Guide.

Example response

Creating collection...
Collection created.
{
    "responseHeader": {
        "status": 0,
        "QTime": 1627
    },
    "success": {
        "": {
            "responseHeader": {
                "status": 0,
                "QTime": 1479
            },
            "core": "example_collection_shard1_replica1"
        }
    }
}
{
    "responseHeader": {
        "status": 0,
        "QTime": 1627
    },
    "success": {
        "": {
            "responseHeader": {
                "status": 0,
                "QTime": 1479
            },
            "core": "example_collection_shard1_replica1"
        }
    }
}

Delete Solr collection

An example of a method that forwards to the Solr Collections API. This Retrieve and Rank resource improves error handling and resiliency of the Solr Collections API.

POST /v1/solr_clusters/{solr_cluster_id}/solr/admin/collections/

Request

Parameter Type Description
solr_cluster_id Path (Required) Cluster ID for the collection.
action Query (Required) Operation to carry out. Use DELETE in this method.
name Query (Required) The name of the collection to delete.
wt Query Writer type. Default is standard (xml). Specifies which QueryResponseWriter to use to process the request. Valid values are declared in the solrconfig.xml file.
Parameter Data type Description
cluster_id string (Required) Cluster ID for the collection.
collection_name string (Required) The name of the collection to delete.
wt string Writer type. Default is json. Specifies which QueryResponseWriter to use to process the request. Valid values are declared in the solrconfig.xml file.

Example request

curl -X POST -u "{username}":"{password}" "https://gateway.watsonplatform.net/retrieve-and-rank/api/v1/solr_clusters/sc1ca23733_faa8_49ce_b3b6_dc3e193264c6/solr/admin/collections" -d "action=DELETE&name=example_collection&wt=json"
var watson = require('watson-developer-cloud');
var retrieve_and_rank = watson.retrieve_and_rank({
  username: '{username}',
  password: '{password}',
  version: 'v1'
});

var params = {
  cluster_id: 'sc1ca23733_faa8_49ce_b3b6_dc3e193264c6',
  collection_name: 'example_collection',
  wt: 'json'
};

retrieve_and_rank.deleteCollection(params,
  function (err, response) {
    if (err)
      console.log('error:', err);
    else
      console.log(JSON.stringify(response, null, 2));
});
RetrieveAndRank service = new RetrieveAndRank();
service.setUsernameAndPassword("{username}","{password}");

cluster.deleteCollection("sc1ca23733_faa8_49ce_b3b6_dc3e193264c6", "example_collection", "json");

Response

For details about the response, see the Solr Collections API in the Apache Solr Reference Guide.

Example response

{
  "responseHeader": {
    "status": 0,
    "QTime": 2
  },
  "collections": [
    "example_collection"
  ]
}

Index documents

Adds content to a Solr index so you can search it.

An example of a method that forwards to Solr. For more information about indexing, see Indexing and Basic Data Operations in the Apache Solr Reference.

You must commit your documents to the index to search for them. For more information about when to commit, see UpdateHandlers in SolrConfig in the Solr Reference.

POST /v1/solr_clusters/{solr_cluster_id}/solr/{collection_name}/update

Request

Parameter Type Description
Content-Type Header (Required) Media type of the content.
solr_cluster_id Path (Required) Cluster ID.
collection_name Path (Required) Collection.
body Body (Required) File that defines the content.
Parameter Data type Description
cluster_id string (Required) Cluster ID.
collection_name string (Required) Collection.
doc array (Required) The content.
Parameter Data type Description
cluster_id string (Required) Cluster ID.
collection_name string (Required) Collection.
doc list (Required) The content.

Example request

curl -X POST -H "Content-Type: application/json" -u "{username}":"{password}" "https://gateway.watsonplatform.net/retrieve-and-rank/api/v1/solr_clusters/sc1ca23733_faa8_49ce_b3b6_dc3e193264c6/solr/example_collection/update" --data-binary @your_docs.json
var watson = require('watson-developer-cloud');
var retrieve_and_rank = watson.retrieve_and_rank({
  username: '{username}',
  password: '{password}',
  version: 'v1'
});

var params = {
  cluster_id: 'sc1ca23733_faa8_49ce_b3b6_dc3e193264c6',
  collection_name: 'example_collection',
};

var doc = {
    id: 1,
    author: 'brenckman,m.',
    bibliography: 'j. ae. scs. 25, 1958, 324.',
    body: 'experimental investigation of the aerodynamics of a wing in a slipstream.   an experimental study of a wing in a propeller slipstream was made in order to determine the spanwise distribution of the lift increase due to slipstream at different angles of attack of the wing and at different free stream to slipstream velocity ratios.',
    title: 'experimental investigation of the aerodynamics of a wing in a slipstream'
};

solrClient = retrieve_and_rank.createSolrClient(params);

console.log('Indexing a document...');
solrClient.add(doc, function (err, response) {
  if (err) {
    console.log('Error indexing document: ', err);
  }
    else {
      console.log('Indexed a document.');
      solrClient.commit(function(err) {
        if(err) {
          console.log('Error committing change: ' + err);
        }
          else {
            console.log('Successfully committed changes.');
          }
      });
    }
});
RetrieveAndRank service = new RetrieveAndRank();
service.setUsernameAndPassword("{username}","{password}");

SolrInputDocument newdoc = new SolrInputDocument();
document.addField("id", 1);
document.addField("author", "brenckman,m.");
document.addField("bibliography", "j. ae. scs. 25, 1958, 324.");
document.addField("body", ""experimental investigation of the aerodynamics of a wing in a slipstream .   an experimental study of a wing in a propeller slipstream was made in order to determine the spanwise distribution of the lift increase due to slipstream at different angles of attack of the wing and at different free stream to slipstream velocity ratios .  the results were intended in part as an evaluation basis for different theoretical treatments of this problem .   the comparative span loading curves, together with supporting evidence, showed that a substantial part of the lift increment produced by the slipstream was due to a /destalling/ or boundary-layer-control effect .  the integrated remaining lift increment, after subtracting this destalling lift, was found to agree well with a potential flow theory .   an empirical evaluation of the destalling effects was made for the specific configuration of the experiment .");
document.addField("title", ""experimental investigation of the aerodynamics of a wing in a slipstream .")

System.out.println("Indexing document...");
UpdateResponse addResponse = solrClient.add("example_collection", newdoc);
System.out.println(addResponse);

// Commit the document to the index so that it will be available for searching.
solrClient.commit("example_collection");
System.out.println("Indexed and committed document.");

Response

For details about the response, see Uploading Data with Index Handlers in the Apache Solr Reference Guide.

Example response

Indexing document...
Indexed and committed document.
Indexing a document...
Indexed a document.
Successfully committed changes.
{
  "responseHeader": {
      "status": 0,
      "QTime": 2784
  }
}

Search Solr standard query parser

Forwards to the Solr standard query parser.

POST /v1/solr_clusters/{solr_cluster_id}/solr/{collection_name}/select

Request

Parameter Type Description
solr_cluster_id Path (Required) Cluster ID.
collection_name Path (Required) The name of the collection to use.
q query (Required) The query. Uses Solr standard query syntax.
Parameter Data type Description
cluster_id string (Required) Cluster ID.
collection_name string (Required) Collection.
query string (Required) The query. Uses Solr standard query syntax.
wt string Writer type. Default is json. Specifies which QueryResponseWriter to use to process the request. Valid values are declared in the solrconfig.xml file.
Parameter Data type Description
cluster_id string (Required) Cluster ID.
collection_name string (Required) Collection.
query string (Required) The query. Uses Solr standard query syntax. See SolrQuery for information about the standard syntax.
wt string Writer type. Default is json. Specifies which QueryResponseWriter to use to process the request. Valid values are declared in the solrconfig.xml file.

Example request

curl -X POST -u "{username}":"{password}" "https://gateway.watsonplatform.net/retrieve-and-rank/api/v1/solr_clusters/sc1ca23733_faa8_49ce_b3b6_dc3e193264c6/solr/example_collection/select?q=what%20is%20the%20basic%20mechanism%20of%20the%20transonic%20aileron%20buzz&wt=json&fl=id,title"
var watson = require('watson-developer-cloud');
var retrieve_and_rank = watson.retrieve_and_rank({
  username: '{username}',
  password: '{password}',
  version: 'v1'
});

var params = {
  cluster_id: 'sc1ca23733_faa8_49ce_b3b6_dc3e193264c6',
  collection_name: 'example_collection',
  wt: 'json'
};

// Get a Solr client for indexing and searching documents.
// See https://github.com/watson-developer-cloud/node-sdk/blob/master/services/retrieve_and_rank/v1.js
solrClient = retrieve_and_rank.create(params);

console.log('Searching all documents.');
var query = solrClient.createQuery();
query.q({ '*' : '*' });

solrClient.search(query, function(err, searchResponse) {
  if(err) {
    console.log('Error searching for documents: ' + err);
  }
    else {
      console.log('Found ' + searchResponse.response.numFound + ' documents.');
      console.log('First document: ' + JSON.stringify(searchResponse.response.docs[0], null, 2));
    }
});
private static final String USERNAME = "{username}";
private static final String PASSWORD = "{password}";
private static final String SOLR_CLUSTER_ID = "{solr_cluster_ID}";

private static HttpSolrClient solrClient;

private static HttpSolrClient getSolrClient(String uri, String username, String password) {
    return new HttpSolrClient(service.getSolrUrl(SOLR_CLUSTER_ID), createHttpClient(uri, username, password));
}

private static HttpClient createHttpClient(String uri, String username, String password) {
    final URI scopeUri = URI.create(uri);

    final BasicCredentialsProvider credentialsProvider = new BasicCredentialsProvider();
    credentialsProvider.setCredentials(new AuthScope(scopeUri.getHost(), scopeUri.getPort()),
        new UsernamePasswordCredentials("{username}", "{password}"));

    final HttpClientBuilder builder = HttpClientBuilder.create()
        .setMaxConnTotal(128)
        .setMaxConnPerRoute(32)
        .setDefaultRequestConfig(RequestConfig.copy(RequestConfig.DEFAULT).setRedirectsEnabled(true).build())
        .setDefaultCredentialsProvider(credentialsProvider)
        .addInterceptorFirst(new PreemptiveAuthInterceptor());
    return builder.build();
}

service = new RetrieveAndRank();
service.setUsernameAndPassword(USERNAME, PASSWORD);
solrClient = getSolrClient(service.getSolrUrl(SOLR_CLUSTER_ID), USERNAME, PASSWORD);
SolrQuery query = new SolrQuery("*:*");
QueryResponse response = solrClient.query("example_collection", query);
System.out.println(response);

Response

The options in the request determine the structure of the response. For details about the response, see the Solr standard query parser.

Example response

{
  "responseHeader": {
    "status": 0,
    "QTime": 168,
    "params": {
      "q": "what is the basic mechanism of the transonic aileron buzz",
      "fl": "id,title",
      "wt": "json"
    }
  },
  "response": {
    "numFound": 164,
    "start": 0,
    "docs": [
      {
        "id": "496",
        "title": [
            " a theory of transonic aileron buzz, neglecting viscous effects ."
        ]
      },
      {
        "id": "1268",
        "title": [
            " stable combustion of a high-velocity gas in a heated boundary layer ."
        ]
      },

      ...

    ]
  }
}
Searching all documents.
Found 1 documents.
First document: {
  "id": "1",
  "author": [
    "brenckman,m."
  ],
  "bibliography": [
    "j. ae. scs. 25, 1958, 324."
  ],
  "body": [
    "experimental investigation of the aerodynamics of a wing in a slipstream.   an experimental study of a wing in a propeller slipstream was made in order to determine the spanwise distribution of the lift increase due to slipstream at different angles of attack of the wing and at different free stream to slipstream velocity ratios."
  ],
  "title": [
    "experimental investigation of the aerodynamics of a wing in a slipstream"
  ],
  "_version_": 1513952036303929300
}

Create ranker

Sends data to create and train a ranker and returns information about the new ranker.

When the operation is successful, the status of the ranker is set to Training. The status must be Available before you can use the ranker.

POST /v1/rankers

Request

Parameter Type Description
training_data Form (Required) Training data in CSV format. The first header must be question_id and the last header must be the relevance label. The other headers are alphanumeric feature names. For details, see Using your own data.
training_metadata Form

Metadata in JSON format.

The metadata identifies an optional name to identify the ranker.

Parameter Type Description
name string The name of the ranker
training string The path of the file that contains the training data for the ranker.

Example request

curl -X POST -u "{username}":"{password}" -F training_data=@train.csv -F training_metadata="{\"name\":\"My ranker\"}" "https://gateway.watsonplatform.net/retrieve-and-rank/api/v1/rankers"
var watson = require('watson-developer-cloud');
var retrieve_and_rank = watson.retrieve_and_rank({
  username: '{username}',
  password: '{password}',
  version: 'v1'
});

var params = {
  training_data: fs.createReadStream('ranker_train.csv'),
  training_metadata: fs.createReadStream('ranker_meta.json')
};

retrieve_and_rank.createRanker(params,
  function(err, response) {
    if (err)
      console.log('error: ', err);
    else
      console.log(JSON.stringify(response, null, 2));
});
RetrieveAndRank service = new RetrieveAndRank();
service.setUsernameAndPassword("{username}","{password}");

Ranker ranker = service.createRanker("ranker1", "./training_data.csv");
System.out.println(ranker);

Response

Name Description
ranker_id Unique identifier for this ranker.
name User-supplied name for the ranker.
created Date and time in Coordinated Universal Time that the ranker was created.
url Link to the ranker.
status The state of the ranker: Non_Existent, Training, Failed, Available, or Unavailable.
status_description Additional detail about the status.

Example response

{
  "ranker_id": "B2E325-rank-67",
  "name": "My ranker",
  "created": "2015-05-28T18:01:57.393Z",
  "url": "https://gateway.watsonplatform.net/retrieve-and-rank/api/v1/rankers/B2E325-rank-67",
  "status": "Training",
  "status_description": "The ranker instance is in its training phase, not yet ready to accept rank requests"
}

List rankers

Retrieves the list of rankers for the service instance.

GET /v1/rankers

Request

No arguments.

Example request

curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/retrieve-and-rank/api/v1/rankers"
var watson = require('watson-developer-cloud');
var retrieve_and_rank = watson.retrieve_and_rank({
  username: '{username}',
  password: '{password}',
  version: 'v1'
});

retrieve_and_rank.listRankers({},
  function(err, response) {
    if (err)
      console.log('error: ', err);
    else
      console.log(JSON.stringify(response, null, 2));
});
RetrieveAndRank service = new RetrieveAndRank();
service.setUsernameAndPassword("{username}","{password}");

List<String> rankers = service.getRankers();
System.out.println(rankers);

Response

Name Description
rankers An array of [rankers] that available for the service instance.
rankers
Name Description
ranker_id Unique identifier for this ranker
url Link to the ranker
name User-supplied name for the ranker
created Date and time in Coordinated Universal Time that the ranker was created

Example response

{
  "rankers": [
    {
      "created": "2015-11-12T16:18:49.472-0500",
      "ranker_id": "F3551Dx1-rank-136",
      "name": "itest-ranker",
      "url": "https://gateway.watsonplatform.net/retrieve-and-rank/api/v1/rankers/F3551Dx1-rank-136"
    },
    {
      "created": "2015-11-12T18:45:57.693-0500",
      "ranker_id": "F3551Dx1-rank-146",
      "name": "itest-ranker",
      "url": "https://gateway.watsonplatform.net/retrieve-and-rank/api/v1/rankers/F3551Dx1-rank-146"
    },
    {
      "created": "2015-12-10T23:18:38.915-0500",
      "ranker_id": "F3551Dx1-rank-562",
      "name": "itest-ranker",
      "url": "https://gateway.watsonplatform.net/retrieve-and-rank/api/v1/rankers/F3551Dx1-rank-562"
    },
    {
      "created": "2015-11-12T16:19:01.255-0500",
      "ranker_id": "F35BD1x2-rank-146",
      "name": "itest-ranker",
      "url": "https://gateway.watsonplatform.net/retrieve-and-rank/api/v1/rankers/F35BD1x2-rank-146"
    },
    {
      "created": "2015-11-20T01:55:44.627-0500",
      "ranker_id": "F35BD1x2-rank-297",
      "name": "itest-ranker",
      "url": "https://gateway.watsonplatform.net/retrieve-and-rank/api/v1/rankers/F35BD1x2-rank-297"
    },
    {
      "created": "2015-10-08T17:59:39.609-0400",
      "ranker_id": "F131F6-rank-249",
      "name": "example_ranker",
      "url": "https://gateway.watsonplatform.net/retrieve-and-rank/api/v1/rankers/F131F6-rank-249"
    },
    {
      "created": "2015-11-12T18:46:06.847-0500",
      "ranker_id": "F35BD1x2-rank-160",
      "name": "itest-ranker",
      "url": "https://gateway.watsonplatform.net/retrieve-and-rank/api/v1/rankers/F35BD1x2-rank-160"
    },
    {
      "created": "2016-01-21T16:46:56.084-0500",
      "ranker_id": "42AF7Ex10-rank-47",
      "name": "Ranker Test",
      "url": "https://gateway.watsonplatform.net/retrieve-and-rank/api/v1/rankers/42AF7Ex10-rank-47"
    }
  ]
}
{
  "rankers": [
    {
      "ranker_id": "B2E325-rank-67",
      "url": "https://gateway.watsonplatform.net/retrieve-and-rank/api/v1/rankers/B2E325-rank-67",
      "name": "My ranker",
      "created": "2015-05-28T18:01:57.393Z"
    }
  ]
}

Get information about a ranker

Returns status and other information about a ranker.

GET /v1/rankers/{ranker_id}

Request

Parameter Type Description
ranker_id Path (Required) ID of the ranker to query.

Example request

curl -u "{username}":"{password}"  "https://gateway.watsonplatform.net/retrieve-and-rank/api/v1/rankers/B2E325-rank-67"
var watson = require('watson-developer-cloud');
var retrieve_and_rank = watson.retrieve_and_rank({
  username: '{username}',
  password: '{password}',
  version: 'v1'
});

var params = {
  ranker_id: 'B2E325-rank-67',
};

retrieve_and_rank.rankerStatus(params,
  function(err, response) {
    if (err)
      console.log('error:', err);
    else
      console.log(JSON.stringify(response, null, 2));
});
RetrieveAndRank service = new RetrieveAndRank();
service.setUsernameAndPassword("{username}","{password}");

Ranker ranker = service.getRankerStatus("B2E325-rank-67");
System.out.println(ranker);

Response

Name Description
ranker_id Unique identifier for this ranker.
name User-supplied name for the ranker.
created Date and time in Coordinated Universal Time that the ranker was created.
url Link to the ranker.
status The state of the ranker: Non_Existent, Training, Failed, Available, or Unavailable.
status_description Additional detail about the status.

Example response

{
  "ranker_id": "B2E325-rank-67",
  "name": "My ranker",
  "created": "2015-05-28T18:01:57.393Z",
  "url": "https://gateway.watsonplatform.net/retrieve-and-rank/api/v1/rankers/B2E325-rank-67",
  "status": "Available",
  "status_description": "The ranker instance is now available and is ready to take ranker requests."
}

Delete ranker

Deletes a ranker.

DELETE /v1/rankers/{ranker_id}

Request

Parameter Type Description
ranker_id Path (Required) ID of the ranker to delete.

Example request

curl -X DELETE -u "{username}":"{password}" "https://gateway.watsonplatform.net/retrieve-and-rank/api/v1/rankers/B2E325-rank-67"
var watson = require('watson-developer-cloud');
var retrieve_and_rank = watson.retrieve_and_rank({
  username: '{username}',
  password: '{password}',
  version: 'v1'
});

var params = {
  ranker_id: 'B2E325-rank-67',
};

retrieve_and_rank.deleteRanker(params,
  function(err, response) {
    if (err)
      console.log('error:', err);
    else
      console.log(JSON.stringify(response, null, 2));
});
RetrieveAndRank service = new RetrieveAndRank();
service.setUsernameAndPassword("{username}","{password}");

service.deleteRanker("B2E325-rank-67");

Response

Empty object

Example response

{}

Rank

Returns the top answer and a list of ranked answers with their ranked scores and confidence values. Use the Get information about a ranker method to retrieve the status.

Use this method to return answers when you train the ranker with custom features. In most cases, you can use the Search and rank method.

POST /v1/rankers/{ranker_id}/rank

Request

Parameter Type Description
ranker_id Path (Required) ID of the ranker to use.
answer_data File (Required) The CSV file that contains the search results you want to rank. The first column header of the CSV must be labeled answer_id. The remaining column headers must match the names of the features in the training data that was used when this ranker was created.

Example request

curl -X POST -u "{username}":"{password}" -F answer_data=@answer.csv "https://gateway.watsonplatform.net/retrieve-and-rank/api/v1/rankers/B2E325-rank-67/rank"
var watson = require('watson-developer-cloud');
var retrieve_and_rank = watson.retrieve_and_rank({
  username: '{username}',
  password: '{password}',
  version: 'v1'
});

var params = {
  ranker_id: 'B2E325-rank-67',
  answer_data: fs.createReadStream('answer.csv'),
};

retrieve_and_rank.rank(params,
  function(err, response) {
    if (err)
      console.log('error: ', err);
    else
      console.log(JSON.stringify(response, null, 2));
});
RetrieveAndRank service = new RetrieveAndRank();
service.setUsernameAndPassword("{username}","{password}");

Ranking ranking = service.rank("B2E325-rank-67", "./answer.csv", 10);
System.out.println(ranking);
      

Response

Name Description
ranker_id Unique identifier for this ranker.
name Name of this ranker.
url Link to the ranker.
top_answer The answer with the highest score.
answers An array of answers that are sorted in descending order of score.
Answers
Name Description
answer_id Pointer to the answer in the collection.
score The rank of an answer among the candidate answers. Higher values represent higher relevance. The maximum score is the total number of candidate answers in the answer_data. You can use the score to sort the answers within the response.
confidence A decimal percentage from 0 - 1 that represents the preference that Watson has for this answer. Higher values represent higher confidences.

Example response

{
  "ranker_id": "B2E325-rank-67",
  "name": "My ranker",
  "url": "https://gateway.watsonplatform.net/retrieve-and-rank/api/v1/rankers/B2E325-rank-67",
  "top_answer": "Answer1",
  "answers": [
    {
      "answer_id": "Answer1",
      "score": 10,
      "confidence": 0.726231142375928
    },
    {
      "answer_id": "Answer23",
      "score": 9,
      "confidence": 0.6511395912945229
    },
    {
      "answer_id": "Answer3",
      "score": 8,
      "confidence": 0.45183959129452295
    }, 
    {
    ... <-- additional answers
    }
  ]
}

Search and rank

Return reranked results for your query. The request is similar to the Search Solr standard query parser method, but includes the ranker_id and, in the default configuration, fcselect replaces the select request handler.

Note: The Java API uses the fcselect request handler automatically if you use the example solrconfig.xml configuration file described and available for download at Configuring the Retrieve and Rank service.

POST /v1/solr_clusters/{solr_cluster_id}/solr/{collection_name}/fcselect

Request

Parameter Type Description
solr_cluster_id Path (Required) Cluster ID.
collection_name Path (Required) The name of the collection to use.
ranker_id Query (Required) The trained ranker to query.
q query (Required) The query. Uses Solr standard query syntax.
Parameter Type Description
solr_cluster_id string (Required) Cluster ID.
collection_name string (Required) The name of the collection to use.
ranker_id String (Required) The trained ranker to query.
query string (Required) The query. Uses Solr standard query syntax. See SolrQuery for information about the standard syntax.
Parameter Data type Description
cluster_id string (Required) Cluster ID.
collection_name string (Required) Collection.
ranker_id Query (Required) The trained ranker to query.
query string (Required) The query. Uses Solr standard query syntax.
wt string Writer type. Default is json. Specifies which QueryResponseWriter to use to process the request. Valid values are declared in the solrconfig.xml file.

Example request

curl -X POST -u "{username}":"{password}" "https://gateway.watsonplatform.net/retrieve-and-rank/api/v1/solr_clusters/sc1ca23733_faa8_49ce_b3b6_dc3e193264c6/solr/example_collection/fcselect?ranker_id=B2E325-rank-67&q=what%20is%20the%20basic%20mechanism%20of%20the%20transonic%20aileron%20buzz&wt=json&fl=id,title"
var watson  = require('watson-developer-cloud');
var retrieve_and_rank = watson.retrieve_and_rank({
  username: '{username}',
  password: '{password}',
  version: 'v1'
});

var params = {
  cluster_id: 'sc1ca23733_faa8_49ce_b3b6_dc3e193264c6',
  collection_name: 'example_collection'
};

//  Use a querystring parser to encode output.
var qs = require('qs');

// Get a Solr client for indexing and searching documents.
// See https://github.com/watson-developer-cloud/node-sdk/blob/master/services/retrieve_and_rank/v1.js
solrClient = retrieve_and_rank.createSolrClient(params);

var ranker_id = 'B2E325-rank-67';
var question  = 'what is the basic mechanism of the transonic aileron buzz';
var query     = qs.stringify({q: question, ranker_id: ranker_id, fl: 'id,title'});

solrClient.get('fcselect', query, function(err, searchResponse) {
  if(err) {
    console.log('Error searching for documents: ' + err);
  }
    else {
      console.log(JSON.stringify(searchResponse.response.docs, null, 2));
    }
});
private static final String USERNAME = "{username}";
private static final String PASSWORD = "{password}";
private static final String SOLR_CLUSTER_ID = "{solr_cluster_ID}";

private static HttpSolrClient solrClient;

private static HttpSolrClient getSolrClient(String uri, String username, String password) {
    return new HttpSolrClient(service.getSolrUrl(SOLR_CLUSTER_ID), createHttpClient(uri, username, password));
}

private static HttpClient createHttpClient(String uri, String username, String password) {
    final URI scopeUri = URI.create(uri);

    final BasicCredentialsProvider credentialsProvider = new BasicCredentialsProvider();
    credentialsProvider.setCredentials(new AuthScope(scopeUri.getHost(), scopeUri.getPort()),
        new UsernamePasswordCredentials("{username}", "{password}"));

    final HttpClientBuilder builder = HttpClientBuilder.create()
        .setMaxConnTotal(128)
        .setMaxConnPerRoute(32)
        .setDefaultRequestConfig(RequestConfig.copy(RequestConfig.DEFAULT).setRedirectsEnabled(true).build())
        .setDefaultCredentialsProvider(credentialsProvider)
        .addInterceptorFirst(new PreemptiveAuthInterceptor());
    return builder.build();
}

service = new RetrieveAndRank();
service.setUsernameAndPassword(USERNAME, PASSWORD);
solrClient = getSolrClient(service.getSolrUrl(SOLR_CLUSTER_ID), USERNAME, PASSWORD);
SolrQuery query = new SolrQuery("what is the basic mechanism of the transonic aileron buzz");
query.setParam("ranker_id", "B2E325-rank-67");
query.setRequestHandler("/fcselect"); // use if your solrconfig.xml file does not specify fcselect as the default request handler
QueryResponse response = solrClient.query("example_collection", query);
System.out.println(response);

Response

The results are similar to the Search Solr standard query parser method except that the results are reranked according to the specified ranker.

Example response

{
  "responseHeader": {
    "status": 0,
    "QTime": 3
  },
  "response": {
    "numFound": 164,
    "start": 0,
    "docs": [
      {
        "id": "313",
        "title": [
          "on alternative forms for the basic equations of transonic flow theory ."
        ]
      },
      {
        "id": "496",
        "title": [
          "a theory of transonic aileron buzz, neglecting viscous effects ."
        ]
      },
      {
        "id": "903",
        "title": [
          "two dimensional transonic unsteady flow with shock waves ."
        ]
      },

      ...

    ]
  }
}
Found 164 documents.
[
  {
    "id": "313",
    "title": [
      "on alternative forms for the basic equations of transonic flow theory ."
    ]
  },
  {
    "id": "496",
    "title": [
      "a theory of transonic aileron buzz, neglecting viscous effects ."
    ]
  },
  {
    "id": "903",
    "title": [
      "two dimensional transonic unsteady flow with shock waves ."
    ]
  },

  ...

]

Get cluster statistics

Retrieves disk and memory usage about a Solr cluster.

GET  /v1/solr_clusters/{solr_cluster_id}/stats

Request

Parameter Type Description
solr_cluster_id Path (Required) Cluster ID.

Example request

curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/retrieve-and-rank/api/v1/solr_clusters/sc1ca23733_faa8_49ce_b3b6_dc3e193264c6/stats"
var watson = require('watson-developer-cloud');
var retrieve_and_rank = watson.retrieve_and_rank({
  username: '{username}',
  password: '{password}',
  version: 'v1'
});

var params = {
  cluster_id: 'sc1ca23733_faa8_49ce_b3b6_dc3e193264c6'
};

retrieve_and_rank.getClusterStats(params,
  function(err, response) {
    if (err)
      console.log('error:', err);
    else
      console.log(JSON.stringify(response, null, 2));
});
RetrieveAndRank service = new RetrieveAndRank();
service.setUsernameAndPassword("{username}","{password}");

System.out.println(service.getSolrClusterStats("sc1ca23733_faa8_49ce_b3b6_dc3e193264c6"));

Response

Name Description
disk_usage Summary of disk-usage statistics for the Solr cluster.
used_bytes Number of bytes used on the cluster's disk capacity.
total_bytes Total number of bytes available in the cluster's disk capacity.
used Amount of disk capacity used, in KB or GB format.
total Total amount of the cluster's disk capacity, in KB or GB format.
percent_used Percentage of the cluster's disk capacity that is being used.
memory_usage Summary of memory-usage statistics for the Solr cluster.
used_bytes Number of bytes used in the cluster's memory capacity.
total_bytes Total number of bytes available in the cluster's memory capacity.
used Amount of memory capacity used, in KB or GB format.
total Total amount of the cluster's memory capacity, in KB or GB format.
percent_used Percentage of the cluster's memory capacity that is being used.

Example response

{
 "disk_usage": {
   "used_bytes": 1887,
   "total_bytes": 34359738368,
   "used": "1.8428 KB",
   "total": "32 GB",
   "percent_used": 5.49189280718565E-6
 },
 "memory_usage": {
   "used_bytes": 1126281216,
   "total_bytes": 4194304000,
   "used": "1.0489 GB",
   "total": "3.9063 GB",
   "percent_used": 26.85263671875
 }
}

Resize a Solr cluster

Resize a Solr cluster. For information about cluster sizing and units, see Sizing your Retrieve and Rank cluster.

Resizing a cluster is an asynchronous operation. To check on the status of a resizing operation, use the get status of a cluster resize operation method.

Resizing a cluster has the following limitations:

  • You cannot resize a free cluster to a higher-capacity paid cluster.

  • If your cluster is from one (1) to seven (7) units, you can resize to a maximum of 7 units.

  • The resize operation is asynchronous and does not issue progress or completion messages. You can monitor its progress as described in Get status of a cluster resize operation.

PUT  /v1/solr_clusters/{solr_cluster_id}/cluster_size -d '{ "cluster_size" : "{new_cluster_size}" }'

Request

Parameter Type Description
solr_cluster_id Path (Required) Cluster ID.
new_cluster_size Integer (Required) Requested new size of the Solr cluster, in units. The permitted range is 1 to 7 units (but see the list of limitations regarding cluster resizing). For information about units, see Sizing your Retrieve and Rank cluster.

Example request

curl -X PUT -H "Content-Type: application/json" -u "{username}":"{password}"  "https://gateway.watsonplatform.net/retrieve-and-rank/api/v1/solr_clusters/sc1ca23733_faa8_49ce_b3b6_dc3e193264c6/cluster_size" -d '{ "cluster_size": "2" }'
Not currently supported.
RetrieveAndRank service = new RetrieveAndRank();
service.setUsernameAndPassword("{username}","{password}");

service.resizeCluster("sc1ca23733_faa8_49ce_b3b6_dc3e193264c6", "2");

Response

Empty object

Example response

{}

Get status of a cluster resize operation

Get the status of a Solr cluster resize operation.

GET  /v1/solr_clusters/{solr_cluster_id}/cluster_size

Request

Parameter Type Description
solr_cluster_id Path (Required) Cluster ID.

Example request

curl -u "{username}":"{password}" "https://gateway.watsonplatform.net/retrieve-and-rank/api/v1/solr_clusters/sc1ca23733_faa8_49ce_b3b6_dc3e193264c6/cluster_size"
Not currently supported.
RetrieveAndRank service = new RetrieveAndRank();
service.setUsernameAndPassword("{username}","{password}");

service.pollResizeOperationStatus("sc1ca23733_faa8_49ce_b3b6_dc3e193264c6");

Response

Name Description
cluster_id Cluster ID.
cluster_size Current size of the cluster.
target_cluster_size Target size of the cluster.
message Message from the resize request.
status Status of the resizing request.

Example response

{
    "cluster_id":"sce94ccf57_1ee8_410b_8e67_3b2b3311a994",
    "cluster_size":2,
    "target_cluster_size":3,
    "message":"WRRCSR027: Resizing cluster [sc1ca23733_faa8_49ce_b3b6_dc3e193264c6] from size [2] to size [3].",
    "status":"RESIZING"
}

Data collection

By default, Bluemix collects data from all requests and uses the data to improve the services. If you do not want to share your data, specify the header parameter x-watson-learning-opt-out with the value 1 or true for all requests. If you do not specify this header in all payload data, data is collected and used to improve the service.

Error handling

The Retrieve and Rank service uses standard HTTP response codes to display whether a method completed successfully. A 200 response always indicates success. A 400 type response is some sort of failure and a 500 type response usually indicates an internal system error.

Error information

Status Description
400 - Bad Request Likely caused by one of these issues:
  • Missing or malformed data.
  • Invalid Solr cluster size.
  • Attempt to delete a configuration that is used by a collection.
  • The set of training data is too small.
401 - Unauthorized No API key provided, or the API key provided was not valid.
403 - Forbidden The method is not allowed. Might be caused by insufficient permissions for a Solr cluster.
404 - Not Found The requested item or parameter doesn't exist.
409 - Conflict This user or service instance has the maximum number of Solr clusters. Or the Solr configuration that you are trying to create already exists.
415 - Unsupported Media Type The request is in a media type that the server doesn’t understand.
500 - Internal Server Error Something is wrong on our end. Resubmit the request later.

Error format

Name Description
description Error description
error Error message
code HTTP status code

Example error request

curl -u "{username}":"{password}" -F training_metadata="{\"name\":\"My ranker\"}" "https://gateway.watsonplatform.net/retrieve-and-rank/api/v1/rankers"
var watson = require('watson-developer-cloud');
var retrieve_and_rank = watson.retrieve_and_rank({
  username: '{username}',
  password: '{password}',
  // missing version number
  version: ''
});

var params = {
  cluster_id: 'sc1ca23733_faa8_49ce_b3b6_dc3e193264c6',
  config_name: 'example_config'
};

retrieve_and_rank.getConfig(params).pipe(fs.createWriteStream('config_example.zip'));
RetrieveAndRank service = new RetrieveAndRank();
service.setUsernameAndPassword("{username}","{password}");

// missing configuration name
Path FROM = service.getSolrClusterConfigurationZip("sc1ca23733_faa8_49ce_b3b6_dc3e193264c6", "");
Path TO = Paths.get(".");
CopyOption[] options = new CopyOption[]{
  StandardCopyOption.REPLACE_EXISTING,
  StandardCopyOption.COPY_ATTRIBUTES
};
Files.copy(FROM, TO, options);

Example error response

{
  "description": "No training data is specified. The form field 'training_data' should contain the training CSV and 'training_metadata' should contain a JSON metadata string.",
  "error": "Missing training data",
  "code": 400
}