Apache Solr open-source search software
SOLR-12224: Add APIs to read collection properties (#4071)
Jason Gerlowski9ead8599b197
diff --git a/changelog/unreleased/SOLR-12224-add-collprop-read-apis.yml b/changelog/unreleased/SOLR-12224-add-collprop-read-apis.ymlnew file mode 100644index 00000000000..3372502b7a4--- /dev/null+++ b/changelog/unreleased/SOLR-12224-add-collprop-read-apis.yml@@ -0,0 +1,8 @@+# See https://github.com/apache/solr/blob/main/dev-docs/changelog.adoc+title: Create new v2 APIs for listing and reading collection properties ("collprops")+type: added # added, changed, fixed, deprecated, removed, dependency_update, security, other+authors:+ - name: Jason Gerlowski+links:+ - name: SOLR-12224+ url: https://issues.apache.org/jira/browse/SOLR-12224diff --git a/solr/api/src/java/org/apache/solr/client/api/endpoint/CollectionPropertyApi.java b/solr/api/src/java/org/apache/solr/client/api/endpoint/CollectionPropertyApi.javaindex 8c69aa3ce4c..a4fd54de8db 100644--- a/solr/api/src/java/org/apache/solr/client/api/endpoint/CollectionPropertyApi.java+++ b/solr/api/src/java/org/apache/solr/client/api/endpoint/CollectionPropertyApi.java@@ -18,16 +18,36 @@ package org.apache.solr.client.api.endpoint;import io.swagger.v3.oas.annotations.Operation;import jakarta.ws.rs.DELETE;+import jakarta.ws.rs.GET;import jakarta.ws.rs.PUT;import jakarta.ws.rs.Path;import jakarta.ws.rs.PathParam;+import org.apache.solr.client.api.model.GetCollectionPropertyResponse;+import org.apache.solr.client.api.model.ListCollectionPropertiesResponse;import org.apache.solr.client.api.model.SolrJerseyResponse;import org.apache.solr.client.api.model.UpdateCollectionPropertyRequestBody;/** V2 API definitions for modifying collection-level properties. */-@Path("/collections/{collName}/properties/{propName}")+@Path("/collections/{collName}/properties")public interface CollectionPropertyApi {+ @GET+ @Operation(+ summary = "List all properties for the specified collection",+ tags = {"collection-properties"})+ ListCollectionPropertiesResponse listCollectionProperties(@PathParam("collName") String collName)+ throws Exception;++ @GET+ @Path("/{propName}")+ @Operation(+ summary = "Get the value of a specific collection property",+ tags = {"collection-properties"})+ GetCollectionPropertyResponse getCollectionProperty(+ @PathParam("collName") String collName, @PathParam("propName") String propName)+ throws Exception;+@PUT+ @Path("/{propName}")@Operation(summary = "Create or update a collection property",tags = {"collection-properties"})@@ -38,6 +58,7 @@ public interface CollectionPropertyApi {throws Exception;@DELETE+ @Path("/{propName}")@Operation(summary = "Delete the specified collection property from the collection",tags = {"collection-properties"})diff --git a/solr/api/src/java/org/apache/solr/client/api/model/GetCollectionPropertyResponse.java b/solr/api/src/java/org/apache/solr/client/api/model/GetCollectionPropertyResponse.javanew file mode 100644index 00000000000..0da15ee34bb--- /dev/null+++ b/solr/api/src/java/org/apache/solr/client/api/model/GetCollectionPropertyResponse.java@@ -0,0 +1,28 @@+/*+ * Licensed to the Apache Software Foundation (ASF) under one or more+ * contributor license agreements. See the NOTICE file distributed with+ * this work for additional information regarding copyright ownership.+ * The ASF licenses this file to You under the Apache License, Version 2.0+ * (the "License"); you may not use this file except in compliance with+ * the License. You may obtain a copy of the License at+ *+ * http://www.apache.org/licenses/LICENSE-2.0+ *+ * Unless required by applicable law or agreed to in writing, software+ * distributed under the License is distributed on an "AS IS" BASIS,+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+ * See the License for the specific language governing permissions and+ * limitations under the License.+ */+package org.apache.solr.client.api.model;++import com.fasterxml.jackson.annotation.JsonProperty;+import io.swagger.v3.oas.annotations.media.Schema;++/** The Response for the v2 "get collection property" API */+public class GetCollectionPropertyResponse extends SolrJerseyResponse {++ @Schema(description = "The value of the collection property.")+ @JsonProperty("value")+ public String value;+}diff --git a/solr/api/src/java/org/apache/solr/client/api/model/ListCollectionPropertiesResponse.java b/solr/api/src/java/org/apache/solr/client/api/model/ListCollectionPropertiesResponse.javanew file mode 100644index 00000000000..74479ebf914--- /dev/null+++ b/solr/api/src/java/org/apache/solr/client/api/model/ListCollectionPropertiesResponse.java@@ -0,0 +1,29 @@+/*+ * Licensed to the Apache Software Foundation (ASF) under one or more+ * contributor license agreements. See the NOTICE file distributed with+ * this work for additional information regarding copyright ownership.+ * The ASF licenses this file to You under the Apache License, Version 2.0+ * (the "License"); you may not use this file except in compliance with+ * the License. You may obtain a copy of the License at+ *+ * http://www.apache.org/licenses/LICENSE-2.0+ *+ * Unless required by applicable law or agreed to in writing, software+ * distributed under the License is distributed on an "AS IS" BASIS,+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+ * See the License for the specific language governing permissions and+ * limitations under the License.+ */+package org.apache.solr.client.api.model;++import com.fasterxml.jackson.annotation.JsonProperty;+import io.swagger.v3.oas.annotations.media.Schema;+import java.util.Map;++/** The Response for the v2 "list collection properties" API */+public class ListCollectionPropertiesResponse extends SolrJerseyResponse {++ @Schema(description = "The properties for the collection.")+ @JsonProperty("properties")+ public Map<String, String> properties;+}diff --git a/solr/core/src/java/org/apache/solr/handler/admin/api/CollectionProperty.java b/solr/core/src/java/org/apache/solr/handler/admin/api/CollectionProperty.javaindex 55da1ea0d53..c68e6ce21f2 100644--- a/solr/core/src/java/org/apache/solr/handler/admin/api/CollectionProperty.java+++ b/solr/core/src/java/org/apache/solr/handler/admin/api/CollectionProperty.java@@ -18,9 +18,14 @@package org.apache.solr.handler.admin.api;import static org.apache.solr.security.PermissionNameProvider.Name.COLL_EDIT_PERM;+import static org.apache.solr.security.PermissionNameProvider.Name.COLL_READ_PERM;+import jakarta.inject.Inject;import java.io.IOException;+import java.util.Map;import org.apache.solr.client.api.endpoint.CollectionPropertyApi;+import org.apache.solr.client.api.model.GetCollectionPropertyResponse;+import org.apache.solr.client.api.model.ListCollectionPropertiesResponse;import org.apache.solr.client.api.model.SolrJerseyResponse;import org.apache.solr.client.api.model.UpdateCollectionPropertyRequestBody;import org.apache.solr.common.SolrException;@@ -31,13 +36,13 @@ import org.apache.solr.request.SolrQueryRequest;import org.apache.solr.response.SolrQueryResponse;/**- * V2 API implementations for modifying collection-level properties.+ * V2 API implementations for managing collection-level properties.*- * <p>These APIs (PUT and DELETE /api/collections/collName/properties/propName) are analogous to the- * v1 /admin/collections?action=COLLECTIONPROP command.+ * <p>These APIs are analogous to the v1 /admin/collections?action=COLLECTIONPROP command.*/public class CollectionProperty extends AdminAPIBase implements CollectionPropertyApi {+ @Injectpublic CollectionProperty(CoreContainer coreContainer,SolrQueryRequest solrQueryRequest,@@ -45,6 +50,52 @@ public class CollectionProperty extends AdminAPIBase implements CollectionPropersuper(coreContainer, solrQueryRequest, solrQueryResponse);}+ @Override+ @PermissionName(COLL_READ_PERM)+ public ListCollectionPropertiesResponse listCollectionProperties(String collName)+ throws Exception {+ final var response = instantiateJerseyResponse(ListCollectionPropertiesResponse.class);+ ensureRequiredParameterProvided("collName", collName);+ fetchAndValidateZooKeeperAwareCoreContainer();+ recordCollectionForLogAndTracing(collName, solrQueryRequest);++ String resolvedCollection = coreContainer.getAliases().resolveSimpleAlias(collName);+ CollectionProperties cp =+ new CollectionProperties(coreContainer.getZkController().getZkClient());+ Map<String, String> properties = cp.getCollectionProperties(resolvedCollection);++ // Handle null case - return empty map instead of null+ response.properties = (properties != null) ? properties : Map.of();++ return response;+ }++ @Override+ @PermissionName(COLL_READ_PERM)+ public GetCollectionPropertyResponse getCollectionProperty(String collName, String propName)+ throws Exception {+ final var response = instantiateJerseyResponse(GetCollectionPropertyResponse.class);+ ensureRequiredParameterProvided("collName", collName);+ ensureRequiredParameterProvided("propName", propName);+ fetchAndValidateZooKeeperAwareCoreContainer();+ recordCollectionForLogAndTracing(collName, solrQueryRequest);++ String resolvedCollection = coreContainer.getAliases().resolveSimpleAlias(collName);+ CollectionProperties cp =+ new CollectionProperties(coreContainer.getZkController().getZkClient());+ Map<String, String> properties = cp.getCollectionProperties(resolvedCollection);++ if (properties != null && properties.containsKey(propName)) {+ response.value = properties.get(propName);+ } else {+ throw new SolrException(+ SolrException.ErrorCode.NOT_FOUND,+ "Property '" + propName + "' not found for collection '" + collName + "'");+ }++ return response;+ }+@Override@PermissionName(COLL_EDIT_PERM)public SolrJerseyResponse createOrUpdateCollectionProperty(diff --git a/solr/core/src/test/org/apache/solr/cloud/CollectionsAPISolrJTest.java b/solr/core/src/test/org/apache/solr/cloud/CollectionsAPISolrJTest.javaindex 992ec12f450..60636d30c92 100644--- a/solr/core/src/test/org/apache/solr/cloud/CollectionsAPISolrJTest.java+++ b/solr/core/src/test/org/apache/solr/cloud/CollectionsAPISolrJTest.java@@ -49,6 +49,7 @@ import org.apache.solr.client.solrj.SolrResponse;import org.apache.solr.client.solrj.SolrServerException;import org.apache.solr.client.solrj.impl.CloudSolrClient;import org.apache.solr.client.solrj.request.CollectionAdminRequest;+import org.apache.solr.client.solrj.request.CollectionPropertiesApi;import org.apache.solr.client.solrj.request.CollectionsApi;import org.apache.solr.client.solrj.request.CoreAdminRequest;import org.apache.solr.client.solrj.request.V2Request;@@ -536,7 +537,7 @@ public class CollectionsAPISolrJTest extends SolrCloudTestCase {}@Test- public void testCollectionProp() throws InterruptedException, IOException, SolrServerException {+ public void testCollectionProp() throws Exception {String collectionName = getSaferTestName();final String propName = "testProperty";@@ -554,18 +555,43 @@ public class CollectionsAPISolrJTest extends SolrCloudTestCase {CollectionAdminRequest.setCollectionProperty(collectionName, propName, null).process(cluster.getSolrClient());checkCollectionProperty(collectionName, propName, null);++ // Test that "list-properties" returns all properties+ CollectionAdminRequest.setCollectionProperty(collectionName, propName + "1", "prop1Val")+ .process(cluster.getSolrClient());+ CollectionAdminRequest.setCollectionProperty(collectionName, propName + "2", "prop2Val")+ .process(cluster.getSolrClient());+ final var allProperties =+ new CollectionPropertiesApi.ListCollectionProperties(collectionName)+ .process(cluster.getSolrClient())+ .properties;+ assertEquals(2, allProperties.size());+ assertEquals("prop1Val", allProperties.get(propName + "1"));+ assertEquals("prop2Val", allProperties.get(propName + "2"));++ // Test GET single property API+ final var prop1Response =+ new CollectionPropertiesApi.GetCollectionProperty(collectionName, propName + "1")+ .process(cluster.getSolrClient());+ assertEquals("prop1Val", prop1Response.value);++ final var prop2Response =+ new CollectionPropertiesApi.GetCollectionProperty(collectionName, propName + "2")+ .process(cluster.getSolrClient());+ assertEquals("prop2Val", prop2Response.value);}private void checkCollectionProperty(String collection, String propertyName, String propertyValue)- throws InterruptedException {+ throws Exception {TimeOut timeout = new TimeOut(TIMEOUT, TimeUnit.MILLISECONDS, TimeSource.NANO_TIME);while (!timeout.hasTimedOut()) {- Thread.sleep(10);- if (Objects.equals(- cluster.getZkStateReader().getCollectionProperties(collection).get(propertyName),- propertyValue)) {+ final var listCollPropRsp =+ new CollectionPropertiesApi.ListCollectionProperties(collection)+ .process(cluster.getSolrClient());+ if (Objects.equals(listCollPropRsp.properties.get(propertyName), propertyValue)) {return;}+ Thread.sleep(10);}fail("Timed out waiting for cluster property value");diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/collection-management.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/collection-management.adocindex 7245c66714b..46452619f7c 100644--- a/solr/solr-ref-guide/modules/deployment-guide/pages/collection-management.adoc+++ b/solr/solr-ref-guide/modules/deployment-guide/pages/collection-management.adoc@@ -682,7 +682,8 @@ If the status is anything other than "success", an error message will explain wh[[collectionprop]]== COLLECTIONPROP: Collection Properties-Add, edit or delete a collection property.+Add, update, delete, or retrieve collection properties.+(Listing all collection properties, or fetching an individual property by name are only supported in Solr's v2 API)[tabs#collectionproperty-request]======@@ -691,7 +692,7 @@ V1 API::====[source,bash]-----http://localhost:8983/solr/admin/collections?action=COLLECTIONPROP&name=techproducts_v2&propertyName=propertyName&propertyValue=propertyValue+http://localhost:8983/solr/admin/collections?action=COLLECTIONPROP&name=techproducts&propertyName=propertyName&propertyValue=propertyValue----====@@ -699,20 +700,36 @@ V2 API::+====To create or update a collection property:+[source,bash]-----curl -X PUT http://localhost:8983/api/collections/techproducts_v2/properties/foo -H 'Content-Type: application/json' -d '+curl -X PUT http://localhost:8983/api/collections/techproducts_v2/properties/propertyName -H 'Content-Type: application/json' -d '{- "value": "bar"+ "value": "propertyValue"}'----+To list all properties for a collection:++[source,bash]+----+curl http://localhost:8983/api/collections/techproducts/properties+----++To get a specific collection property by name:++[source,bash]+----+curl http://localhost:8983/api/collections/techproducts/properties/propertyName+----++To delete an existing collection property:[source,bash]-----curl -X DELETE http://localhost:8983/api/collections/techproducts_v2/properties/foo+curl -X DELETE http://localhost:8983/api/collections/techproducts/properties/propertyName----==========@@ -751,9 +768,40 @@ When not provided in v1 requests, the property is deleted.=== COLLECTIONPROP Response-The response will include the status of the request and the properties that were updated or removed.+The response will include the status of the request.If the status is anything other than "0", an error message will explain why the request failed.+For GET requests to list all properties, the response includes a `properties` object containing all property name-value pairs:++[source,json]+----+{+ "responseHeader": {+ "status": 0,+ "QTime": 5+ },+ "properties": {+ "foo": "bar",+ "myProperty": "myValue"+ }+}+----++For GET requests to retrieve a single property, the response includes a `value` field with the property value:++[source,json]+----+{+ "responseHeader": {+ "status": 0,+ "QTime": 3+ },+ "value": "bar"+}+----++If a requested property does not exist, the API will return a 404 error with an appropriate error message.+[[migrate]]== MIGRATE: Migrate Documents to Another Collection