lucene-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ctarg...@apache.org
Subject [1/2] lucene-solr:apiv2: Updates to Core Admin API to add descriptions and doc links
Date Tue, 13 Dec 2016 19:48:54 GMT
Repository: lucene-solr
Updated Branches:
  refs/heads/apiv2 1bbbe678f -> 338b8d594


Updates to Core Admin API to add descriptions and doc links


Project: http://git-wip-us.apache.org/repos/asf/lucene-solr/repo
Commit: http://git-wip-us.apache.org/repos/asf/lucene-solr/commit/8f085a61
Tree: http://git-wip-us.apache.org/repos/asf/lucene-solr/tree/8f085a61
Diff: http://git-wip-us.apache.org/repos/asf/lucene-solr/diff/8f085a61

Branch: refs/heads/apiv2
Commit: 8f085a6122d2e21fc2e64d347a11386e76eeb0b6
Parents: 1bbbe67
Author: Cassandra Targett <ctargett@apache.org>
Authored: Tue Dec 13 12:32:08 2016 -0600
Committer: Cassandra Targett <ctargett@apache.org>
Committed: Tue Dec 13 12:32:08 2016 -0600

----------------------------------------------------------------------
 .../src/resources/apispec/cores.Commands.json   | 36 +++++++-----
 .../src/resources/apispec/cores.Status.json     |  5 +-
 .../resources/apispec/cores.core.Commands.json  | 59 ++++++++++++--------
 .../apispec/cores.core.Commands.split.json      | 19 ++++---
 4 files changed, 71 insertions(+), 48 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/8f085a61/solr/core/src/resources/apispec/cores.Commands.json
----------------------------------------------------------------------
diff --git a/solr/core/src/resources/apispec/cores.Commands.json b/solr/core/src/resources/apispec/cores.Commands.json
index 7b2bcd9..d6419cf 100644
--- a/solr/core/src/resources/apispec/cores.Commands.json
+++ b/solr/core/src/resources/apispec/cores.Commands.json
@@ -1,5 +1,6 @@
 {
-  "documentation": "https://cwiki.apache.org",
+  "documentation": "https://cwiki.apache.org/confluence/display/solr/CoreAdmin+API",
+  "description": "Actions on non-specific cores. See the /cores/{core} endpoint for actions
on specific, named, cores.",
   "methods": [
     "POST"
   ],
@@ -11,62 +12,69 @@
   "commands": {
     "create": {
       "type" : "object",
+      "documentation": "https://cwiki.apache.org/confluence/display/solr/CoreAdmin+API#CoreAdminAPI-CREATE",
+      "description": "Creates a new core. If you are using SolrCloud, you should use the
Collections API instead. While a core for a SolrCloud cluster can be created with this API,
it is considered an expert-level action. The Collections API has commands for creating new
shards and replicas that ensure the safety of those actions within your cluster.",
       "properties": {
         "name": {
           "type": "string",
-          "description": "The core name"
+          "description": "The core name to create. If a core with this name already exists,
an error will be returned."
         },
         "instanceDir": {
           "type": "string",
-          "description": "The core instance dir"
+          "description": "The core instance directory, where files for this core should be
stored. While this parameter is not required, if it is not defined it will default to a path
relative to Solr Home that includes the name you've given the new core. This location MUST
EXIST prior to creating the core, and it must include a conf directory that includes solrconfig.xml
and your schema, either as a schema.xml file or using the managed schema feature."
         },
         "schema": {
           "type": "string",
-          "description": "Name of the schema file to use for the core. Please note that if
you are using a 'managed schema' (the default behavior) then any value for this property which
does not match the effective managedSchemaResourceName will be read once, backed up, and converted
for managed schema use"
+          "description": "Name of the schema file to use for the core. Please note that if
you are using a 'managed schema' (Solr's default behavior) then any value for this property
that does not match the effective managedSchemaResourceName will be read once, backed up,
and converted for managed schema use. If you are using the default name (schema.xml or the
managed schema name), you do not need to define the schema file name."
         },
         "dataDir": {
           "type": "string",
-          "description": "Name of the data directory relative to instanceDir"
+          "description": "Name of the data directory relative to instanceDir. This is where
the index files will be stored."
         },
         "config": {
           "type": "string",
-          "description": "Name of the config file (i.e., solrconfig.xml) relative to instanceDir."
+          "description": "Name of the config file (i.e., solrconfig.xml) relative to instanceDir.
If you are using the default name (solrconfig.xml), you do not need to define the config file
name."
         },
         "configSet": {
           "type": "string",
-          "description": "The configset name"
+          "documentation": "https://cwiki.apache.org/confluence/display/solr/Config+Sets",
+          "description": "The name of a config set to use. The config set must already exist.
The solr.xml file defines the location of the configset base directory, and configuration
files can be shared between cores by defining sub-directories. The files in the named configSet
will be used for the schema and config properties instead of defining them explicitly."
         },
         "loadOnStartup": {
           "type": "boolean",
-          "description": "Load the core on startup"
+          "description": "If true, the core will be loaded on startup. Set to false to enable
lazy loading, where the core will only be loaded if it is referenced or called.",
+          "default": "true"
         },
         "transient": {
           "type": "boolean",
-          "description": "The core may be unloaded if required"
+          "description": "Allows Solr to unload the core if resources are required.",
+          "default": "false"
         },
         "shard": {
           "type": "string",
-          "description": "In SolrCloud mode, which shard does this core belong to"
+          "description": "In SolrCloud mode, the shard this core should belong to."
         },
         "collection": {
           "type": "string",
-          "description": "The collection where this core belongs to"
+          "description": "The name of the collection this core belongs to."
         },
         "props": {
           "type": "object",
+          "documentation": "https://cwiki.apache.org/confluence/display/solr/Defining+core.properties",
+          "description": "Allows adding core.properties for the collection.",
           "additionalProperties": true
         },
         "coreNodeName": {
           "type": "string",
-          "description": "The replica name"
+          "description": "The replica name."
         },
         "numShards": {
           "type":"number",
-          "description":"number of shards"
+          "description":"The number of shards to create for this core."
         },
         "async": {
           "type": "string",
-          "description": "Request ID to track this action which will be processed asynchronously"
+          "description": "Defines a request ID that can be used to track this action after
it's submitted. The action will be processed asynchronously when this is defined."
         }
       },
       "required": [

http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/8f085a61/solr/core/src/resources/apispec/cores.Status.json
----------------------------------------------------------------------
diff --git a/solr/core/src/resources/apispec/cores.Status.json b/solr/core/src/resources/apispec/cores.Status.json
index 64b38cf..9ca0cfb 100644
--- a/solr/core/src/resources/apispec/cores.Status.json
+++ b/solr/core/src/resources/apispec/cores.Status.json
@@ -1,5 +1,6 @@
 {
-  "documentation": "https://cwiki.apache.org",
+  "documentation": "https://cwiki.apache.org/confluence/display/solr/CoreAdmin+API#CoreAdminAPI-STATUS",
+  "description": "Provides status and other information about the status of each core. Individual
cores can be requested by core name.",
   "methods": [
     "GET"
   ],
@@ -11,7 +12,7 @@
     "params": {
       "indexInfo": {
         "type": "boolean",
-        "description": "return index info",
+        "description": "If true, index information will be returned, such as information
about number of documents, deletions, segments, etc. In a large cluster with more than hundreds
of cores, this can take a long time to retrieve. If you have a large cluster, consider setting
this to false.",
         "default": true
       }
     }

http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/8f085a61/solr/core/src/resources/apispec/cores.core.Commands.json
----------------------------------------------------------------------
diff --git a/solr/core/src/resources/apispec/cores.core.Commands.json b/solr/core/src/resources/apispec/cores.core.Commands.json
index 20ad0dd..5049a3a 100644
--- a/solr/core/src/resources/apispec/cores.core.Commands.json
+++ b/solr/core/src/resources/apispec/cores.core.Commands.json
@@ -1,5 +1,6 @@
 {
   "documentation": "https://cwiki.apache.org/confluence/display/solr/CoreAdmin+API",
+  "description": "Actions that are peformed on individual cores, such as reloading, swapping
cores, renaming, and others.",
   "methods": [
     "POST"
   ],
@@ -10,18 +11,22 @@
   },
   "commands": {
     "reload": {
-      "type":"object"
+      "type":"object",
+      "documentation": "https://cwiki.apache.org/confluence/display/solr/CoreAdmin+API#CoreAdminAPI-RELOAD",
+      "description": "Reloads a core. This is useful when you have made changes on disk such
as editing the schema or solrconfig.xml files. Most APIs reload cores automatically, so this
should not be necessary if changes were made with those APIs."
     },
     "swap": {
       "type":"object",
+      "documentation": "https://cwiki.apache.org/confluence/display/solr/CoreAdmin+API#CoreAdminAPI-SWAP",
+      "description": "Swaps the names of two existing Solr cores. This can be used to swap
new content into production. The former core can be swapped back if necessary. Using this
API is not supported in SolrCloud mode.",
       "properties": {
         "with": {
           "type": "string",
-          "description": "The other core name"
+          "description": "The name of the other core to be swapped (the first core name is
included in the request)."
         },
         "async": {
           "type": "string",
-          "description": "Request ID to track this action which will be processed asynchronously"
+          "description": "Defines a request ID that can be used to track this action after
it's submitted. The action will be processed asynchronously when this is defined."
         }
       },
       "required": [
@@ -30,14 +35,16 @@
     },
     "rename": {
       "type": "object",
+      "documentation": "https://cwiki.apache.org/confluence/display/solr/CoreAdmin+API#CoreAdminAPI-RENAME",
+      "description": "Change the name of a core.",
       "properties": {
         "to": {
           "type": "string",
-          "description": "The new name"
+          "description": "The new name for the core."
         },
         "async": {
           "type": "string",
-          "description": "Request ID to track this action which will be processed asynchronously"
+          "description": "Defines a request ID that can be used to track this action after
it's submitted. The action will be processed asynchronously when this is defined."
         }
       },
       "required": [
@@ -46,78 +53,84 @@
     },
     "unload": {
       "type": "object",
+      "documentation": "https://cwiki.apache.org/confluence/display/solr/CoreAdmin+API#CoreAdminAPI-UNLOAD",
+      "description": "Removes a core. Active requests would continue to be processed, but
new requests will not be sent to the new core. If a core is registered under more than one
name, only the name given in the request is removed.",
       "properties": {
         "deleteIndex": {
           "type": "boolean",
-          "description": ""
+          "description": "If true, the index will be removed while unloading the core.",
+          "default": "false"
         },
         "deleteDataDir": {
           "type": "boolean",
-          "description": ""
+          "description": "If true, the data directory and all sub-directories will be removed
while unloading the core.",
+          "default": "false"
         },
         "deleteInstanceDir": {
           "type": "boolean",
-          "description": ""
+          "description": "If true, everything related to the core, including the index, data,
and conf directories, will be removed while unloading the core.",
+          "default": "false"
         },
         "async": {
           "type": "string",
-          "description": "Request ID to track this action which will be processed asynchronously"
+          "description": "Defines a request ID that can be used to track this action after
it's submitted. The action will be processed asynchronously when this is defined."
         }
       }
     },
-
     "merge-indexes": {
       "type":"object",
+      "documentation": "https://cwiki.apache.org/confluence/display/solr/CoreAdmin+API#CoreAdminAPI-MERGEINDEXES",
+      "description":"Merges one or more indexes to another index. The indexes must have completed
commits, and should be locked against writes until the merge is complete to avoid index corruption.
The target core (which is the core that should be used as the endpoint for this command) must
exist before using this command. A commit should also be performed on this core after the
merge is complete.",
       "properties": {
         "indexDir": {
           "type": "array",
+          "description": "A comma-separated list index directories for each source core that
will be merged with the target core.",
           "items": {
             "type": "string"
-          },
-          "description": "Multi-valued, directories that would be merged"
+          }
         },
         "srcCore": {
           "type": "array",
+          "description": "A comma-separated list of the names of each source core to be merged
with the target core.",
           "items": {
             "type": "string"
-          },
-          "description": "Multi-valued, source cores that would be merged."
+          }
         },
         "async": {
           "type": "string",
-          "description": "Request ID to track this action which will be processed asynchronously"
+          "description": "Defines a request ID that can be used to track this action after
it's submitted. The action will be processed asynchronously when this is defined."
         }
       }
     },
+    "split":  { "#include": "cores.core.Commands.split"},
     "request-recovery": {
       "type":"object",
-      "description": "Internal API"
-
+      "documentation": "https://cwiki.apache.org/confluence/display/solr/CoreAdmin+API#CoreAdminAPI-REQUESTRECOVERY",
+      "description": "Manually asks a core to recover by synching with a leader. It may help
SolrCloud clusters where a node refuses to come back up. However, it is considered an expert-level
command, and should be used very carefully."
     },
     "force-prepare-for-leadership": {
       "type": "object",
-      "description": "Internal API"
+      "description": "An internal API used by the Collections API to force leader election.
This should not be used directly by end-users."
     },
-    "split":  { "#include": "cores.core.Commands.split"},
     "prep-recovery": {
       "type": "object",
       "additionalProperties": true,
-      "description": "Internal API"
+      "description": "An internal API used by the Collections API. This should not be used
directly by end-users."
     },
     "request-apply-updates": {
       "type": "object",
       "additionalProperties": true,
-      "description": "Internal API"
+      "description": "An internal API used by the Collections API. This should not be used
directly by end-users."
     },
     "request-sync-shard": {
       "type": "object",
       "additionalProperties": true,
-      "description": "Internal API"
+      "description": "An internal API used by the Collections API. This should not be used
directly by end-users."
     },
     "request-buffer-updates": {
       "type": "object",
       "additionalProperties": true,
-      "description": "Internal API"
+      "description": "An internal API used by the Collections API. This should not be used
directly by end-users."
     }
   }
 }

http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/8f085a61/solr/core/src/resources/apispec/cores.core.Commands.split.json
----------------------------------------------------------------------
diff --git a/solr/core/src/resources/apispec/cores.core.Commands.split.json b/solr/core/src/resources/apispec/cores.core.Commands.split.json
index 1753b52..3aa0a91 100644
--- a/solr/core/src/resources/apispec/cores.core.Commands.split.json
+++ b/solr/core/src/resources/apispec/cores.core.Commands.split.json
@@ -1,33 +1,34 @@
 {
-  "documentation": "https://cwiki.apache.org/confluence/display/solr/CoreAdmin+API",
+  "documentation": "https://cwiki.apache.org/confluence/display/solr/CoreAdmin+API#CoreAdminAPI-SPLIT",
+  "description": "Allows splitting an index into two or more new indexes.",
   "type": "object",
   "properties": {
     "path": {
       "type": "array",
+      "description": "Directory path(s) in which a piece of the index will be written. This
allows splitting the index before creating the cores to contain them. Note if using this approach
that the indexes will not be able to receive updates until a new core has been created to
handle the incoming updates. If you have already created the new cores, you should define
the targetCore property instead.",
       "items": {
         "type": "string"
-      },
-      "description": "the directory path(s) in which a piece of the index will be written"
+      }
     },
     "targetCore": {
       "type": "array",
+      "description": "The target Solr core(s) to which a piece of the index will be merged
(if the target core already contains data). This requires that the cores have already been
created. If the cores have not yet been created, use the path property instead.",
       "items": {
         "type": "string"
-      },
-      "description": "the target Solr core(s) to which a piece of the index will be merged"
+      }
     },
     "splitKey": {
       "type":"string",
-      "description": "The key to be used for splitting the index"
+      "description": "A route key to use for splitting the index. This parameter is optional,
but should not be defined if the ranges parameter is also defined."
     },
     "ranges": {
       "type": "string",
-      "description": "A comma-separated list of hash ranges in hexadecimal format"
+      "description": "A comma-separated list of hexadecimal hash ranges that will be used
to split the core. This parameter is optional, but should not be defined if the splitKey parameter
is also defined."
     },
     "async": {
       "type": "string",
-      "description": "Request ID to track this action which will be processed asynchronously"
+      "description": "Defines a request ID that can be used to track this action after it's
submitted. The action will be processed asynchronously when this is defined. This command
can be long-running, so running it asynchronously is recommended."
     }
   }
 
-}
\ No newline at end of file
+}


Mime
View raw message