From 97623d487f731dd7284a1a072766d6823e6b5ece Mon Sep 17 00:00:00 2001 From: Scott Ivey Date: Mon, 30 Nov 2015 01:39:47 -0500 Subject: [PATCH] api doc updates --- docs/api/javascript_api.md | 122 +++++++++++++----- docs/api/ruby_api.md | 250 ++++++++++++++++++++++++++++++++----- 2 files changed, 311 insertions(+), 61 deletions(-) diff --git a/docs/api/javascript_api.md b/docs/api/javascript_api.md index 0fdb2e4..537b31f 100644 --- a/docs/api/javascript_api.md +++ b/docs/api/javascript_api.md @@ -6,6 +6,8 @@ All of the Javascript client's methods return ES6-style promises. --- +## Similarity Scoring + ### `getTextSimilarity` `(centroidId, text, language = RelevancedClient.Language.EN)` @@ -86,24 +88,8 @@ Returns a future resolving to the score as a double. Resolves to a `RelevancedClient.ECentroidDoesNotExist` exception if either centroid is missing. --- -### `joinCentroid` - -`(centroidId)` - -`-> future[JoinCentroidResponse(id: string, recalculated: bool)]` -Ensures a centroid is up to date before proceeding. -The server automatically recalculates centroids as documents are added and removed. `joinCentroid` provides a way to synchronize with that process. The specific behavior is: - -- If the centroid is up to date, returns immediately. -- If an update job is currently in progress, returns once that job has completed. -- If the centroid is not up to date and no job is executing (because of the cool-off period), immediately starts the update and returns once it is complete. - -The `recalculated` property of the returned `JoinCentroidResponse` indicates whether a recalculation was actually performed. - -Raises `RelevancedClient.ECentroidDoesNotExist` if `centroidId` refers to a nonexistent centroid. - ---- +## Document CRUD ### `createDocument` `(text, language = RelevancedClient.Language.EN)` @@ -130,7 +116,7 @@ Resolves to a `RelevancedClient.EDocumentAlreadyExists` exception if a document --- ### `deleteDocument` -`(id)` +`(documentId)` `-> future[DeleteDocumentResponse(id: string)]` @@ -141,9 +127,36 @@ Resolves to a `RelevancedClient.EDocumentDoesNotExist` exception if the document If the document is associated with any centroids, those associations are automatically invalidated. Most of this invalidation work happens lazily during centroid recomputations. --- +### `multiDeleteDocuments` + +`(documentIds, ignoreMissing=false)` + +`-> MultiDeleteDocumentsResponse(ids: list)` + +Deletes multiple documents on the server. See the `deleteDocument` command for details of document deletion. + +Resolves to a `RelevancedClient.EDocumentDoesNotExist` exception if any of the documents does not exist, unless `ignoreMissing` is `true. + +The `ids` property of the returned response object lists the IDs of the documents that were deleted. If `ignoreMissing=true` was passed, this list will only include the documents that were really deleted (not missing). + + +--- +### `listAllDocuments` + +`()` + +`-> future[ListDocumentsResponse(documents: list)]` + +Lists the IDs of all documents existing on the server. + +This command has no error conditions. + +--- + +## Centroid CRUD ### `createCentroid` -`(id)` +`(centroidId)` `-> future[CreateCentroidResponse(id: string)]` @@ -153,10 +166,24 @@ The `id` property of the returned `CreateCentroidResponse` contains the same ID. Resolves to a `RelevancedClient.ECentroidAlreadyExists` exception if a centroid with the given ID already exists. +--- +### `multiCreateCentroids` + +`(centroidIds, ignoreExisting=false)` + +`-> MultiCreateCentroidsResponse(created: list)` + +Created multiple new centroids on the server. + +Resolves to a `RelevancedClient.ECentroidAlreadyExists` exception if any of the centroids already exists, unless `ignoreExisting=true` was passed. + +The `created` property of the returned `MultiCreateCentroidsResponse` contains a list of IDs of the created centroids. If `ignoreExisting=True` was passed, this list will only include the centroids that were really created (didn't already exist). + + --- ### `deleteCentroid` -`(id)` +`(centroidId)` `-> future[DeleteCentroidResponse(id: string)]` @@ -169,6 +196,30 @@ If the centroid is associated with any documents, the related centroid->document Because documents are independent entities which can be added to many centroids, deleting a given centroid does *not* delete any of the documents it is associated with. It only results in removal of any database entries linking them to the deleted centroid. --- +### `multiDeleteCentroids` +`(centroidIds, ignoreMissing=false)` + +`-> MultiDeleteCentroidsResponse(ids: list)` + +Deletes multiple centroids on the server. See the `deleteCentroid` command for details of centroid deletion. + +Resolves to a `RelevancedClient.ECentroidDoesNotExist` exception if any of the centroids does not exist, unless `ignoreMissing=true` was passed. + +The `ids` property of the returned response object lists the IDs of the centroids that were deleted. If `ignoreMissing=true` was passed, this list will only include the centroids that were really deleted (not missing). + +--- +### `listAllCentroids` + +`()` + +`-> future[ListCentroidsResponse(centroids: list)]` + +Lists the IDs of all centroids existing on the server. + +This command has no error conditions. + +--- +## Centroid-Document CRUD ### `addDocumentsToCentroid` `(centroidId, documentIds, ignoreAlreadyInCentroid=false)` @@ -202,25 +253,34 @@ Resolves to a `RelevancedClient.EDocumentNotInCentroid` exception if any of the If successful, the centroid is automatically recalculated after a cool-down interval. + --- -### `listAllCentroids` -`()` +## Synchronization +### `joinCentroid` -`-> future[ListCentroidsResponse(centroids: list)]` +`(centroidId)` -Lists the IDs of all centroids existing on the server. +`-> future[JoinCentroidResponse(id: string, recalculated: bool)]` -This command has no error conditions. +Ensures a centroid is up to date before proceeding. +The server automatically recalculates centroids as documents are added and removed. `joinCentroid` provides a way to synchronize with that process. The specific behavior is: ---- -### `listAllDocuments` +- If the centroid is up to date, returns immediately. +- If an update job is currently in progress, returns once that job has completed. +- If the centroid is not up to date and no job is executing (because of the cool-off period), immediately starts the update and returns once it is complete. -`()` +The `recalculated` property of the returned `JoinCentroidResponse` indicates whether a recalculation was actually performed. -`-> future[ListDocumentsResponse(documents: list)]` +Raises `RelevancedClient.ECentroidDoesNotExist` if `centroidId` refers to a nonexistent centroid. -Lists the IDs of all documents existing on the server. +--- +### `multiJoinCentroids` -This command has no error conditions. +`(centroidIds)` + +`-> future[MultiJoinCentroidsResponse(ids: list, recalculated: list)]` + +Like `joinCentroid`, but runs against multiple centroids in a single request. +Resolves to a `RelevancedClient.ECentroidDoesNotExist` exception if any of the `centroidIds` refers to a nonexistent centroid. diff --git a/docs/api/ruby_api.md b/docs/api/ruby_api.md index a3ec444..38c6bc1 100644 --- a/docs/api/ruby_api.md +++ b/docs/api/ruby_api.md @@ -1,6 +1,7 @@ # Ruby API --- +## Similarity Scoring ### `get_text_similarity` @@ -80,24 +81,9 @@ Computes cosine similarity of two centroids, returning the score as a double. Raises `ECentroidDoesNotExist` if either centroid is missing. --- -### `join_centroid` - -`(centroid_id)` - -`-> JoinCentroidResponse(id: string, recalculated: bool)` - -Ensures a centroid is up to date before proceeding. -The server automatically recalculates centroids as documents are added and removed. `join_centroid` provides a way to synchronize with that process. The specific behavior is: -- If the centroid is up to date, returns immediately. -- If an update job is currently in progress, returns once that job has completed. -- If the centroid is not up to date and no job is executing (because of the cool-off period), immediately starts the update and returns once it is complete. +## Document CRUD -The `recalculated` property of the returned `JoinCentroidResponse` indicates whether a recalculation was actually performed. - -Raises `ECentroidDoesNotExist` if `centroid_id` refers to a nonexistent centroid. - ---- ### `create_document` `(text, language = Language::EN)` @@ -135,6 +121,59 @@ Raises `EDocumentDoesNotExist` if the document does not exist. If the document is associated with any centroids, those associations are automatically invalidated. Most of this invalidation work happens lazily during centroid recomputations. --- + +### `multi_delete_documents` + +`(document_ids, ignore_missing=false)` + +`-> MultiDeleteDocumentsResponse(ids: list)` + +Deletes multiple documents on the server. See the `delete_document` command for details of document deletion. + +If any of the documents does not exist, raises `EDocumentDoesNotExist` unless `ignore_missing=true` was passed. + +The `ids` property of the returned response object lists the IDs of the documents that were deleted. If `ignore_missing=true` was passed, this list will only include the documents that were really deleted (not missing). + +--- + +### `list_all_documents` + +`()` + +`-> ListDocumentsResponse(documents: list)` + +Lists the IDs of all documents existing on the server. + +This command has no error conditions. + + +--- +### `list_document_range` + +`(offset, count)` + +`-> ListDocumentsResponse(documents: list)` + +Lists a range of IDs of documents existing on the server. With keys sorted alphabetically, skips the first `offset` entries and returns up to `count` entries after that point. + +This command has no error conditions. + +--- +### `list_document_range_from_id` + +`(document_id, count)` + +`-> ListDocumentsResponse(documents: list)` + +Lists a range of IDs of documents existing on the server. With keys sorted alphabetically, skips to `document_id` and then continues to return up to `count` total entries. This count includes the starting `document_id`. + +A missing `document_id` is not an error condition for this command. If `document_id` is not found, iteration will start from the first ID located after it alphabetically. + +This command has no error conditions. + +--- + +## Centroid CRUD ### `create_centroid` `(id)` @@ -147,6 +186,20 @@ The `id` property of the returned `CreateCentroidResponse` contains the same ID. Raises `ECentroidAlreadyExists` if a centroid with the given ID already exists. +--- +### `multi_create_centroids` + +`(centroid_ids, ignore_existing=false)` + +`-> MultiCreateCentroidsResponse(created: list)` + +Created multiple new centroids on the server. + +Raises `ECentroidAlreadyExists` if any of the centroids already exists, unless `ignore_existing=true` was passed. + +The `created` property of the returned `MultiCreateCentroidsResponse` contains a list of IDs of the created centroids. If `ignore_existing=true` was passed, this list will only include the centroids that were really created (didn't already exist). + + --- ### `delete_centroid` @@ -162,10 +215,81 @@ If the centroid is associated with any documents, the related centroid->document Because documents are independent entities which can be added to many centroids, deleting a given centroid does *not* delete any of the documents it is associated with. It only results in removal of any database entries linking them to the deleted centroid. +--- +### `multi_delete_centroids` + +`(centroid_ids, ignore_missing=false)` + +`-> MultiDeleteCentroidsResponse(ids: list)` + +Deletes multiple centroids on the server. See the `delete_centroid` command for details of centroid deletion. + +If any of the centroids does not exist, raises `ECentroidDoesNotExist` unless `ignore_missing=true` was passed. + +The `ids` property of the returned response object lists the IDs of the centroids that were deleted. If `ignore_missing=true` was passed, this list will only include the centroids that were really deleted (not missing). + + +--- +### `list_all_centroids` + +`()` + +`-> ListCentroidsResponse(centroids: list)` + +Lists the IDs of all centroids existing on the server. + +This command has no error conditions. + +--- + +### `list_centroid_range` + +`(offset, count)` + +`-> ListCentroidsResponse(centroids: list)` + +Lists a range of IDs of centroids existing on the server. With keys sorted alphabetically, skips the first `offset` entries and returns up to `count` entries after that point. + +This command has no error conditions. + +--- + +### `list_centroid_range_from_id` + +`(centroid_id, count)` + +`-> ListCentroidsResponse(centroids: list)` + +Lists a range of IDs of centroids existing on the server. With keys sorted alphabetically, skips to `centroid_id` and then continues to return up to `count` total entries. This count includes the starting `centroid_id`. + +A missing `centroid_id` is not an error condition for this command. If `centroid_id` is not found, iteration will start from the first ID located after it alphabetically. + +This command has no error conditions. + +--- + +## Centroid-Document CRUD + +### `add_document_to_centroid` + +`(centroid_id, document_id, ignore_already_in_centroid=false)` + +`-> AddDocumentsToCentroidResponse` + +Associates a single document with a centroid. + +Raises `ECentroidDoesNotExist` if `centroid_id` refers to a nonexistent centroid. + +Raises `EDocumentDoesNotExist` if `document_id` refers to a nonexistent document. + +Raises `EDocumentAlreadyInCentroid` the document is already in the centroid, unless `ignore_already_in_centroid=true` is passed. + +If successful, the centroid is automatically recalculated after a cool-down interval. + --- ### `add_documents_to_centroid` -`(centroid_id, document_ids, ignore_already_in_centroid=False)` +`(centroid_id, document_ids, ignore_already_in_centroid=false)` `-> AddDocumentsToCentroidResponse` @@ -175,14 +299,33 @@ Raises `ECentroidDoesNotExist` if `centroid_id` refers to a nonexistent centroid Raises `EDocumentDoesNotExist` if any of the documents in `document_ids` does not exist. -Raises `EDocumentAlreadyInCentroid` if any of the documents in `document_ids` is already in the centroid, unless `ignore_already_in_centroid=True` is passed. +Raises `EDocumentAlreadyInCentroid` if any of the documents in `document_ids` is already in the centroid, unless `ignore_already_in_centroid=true` is passed. + +If successful, the centroid is automatically recalculated after a cool-down interval. + +--- + +### `remove_document_from_centroid` + +`(centroid_id, document_id, ignore_not_in_centroid=false)` + +`-> RemoveDocumentsFromCentroidResponse` + +Unassociates a single document from a centroid. + +Raises `ECentroidDoesNotExist` if `centroid_id` refers to a nonexistent centroid. + +Raises `EDocumentDoesNotExist` if `document_id` refers to a nonexistent document. + +Raises `EDocumentNotInCentroid` if the document is not currently associated with the centroid, unless `ignore_not_in_centroid=true` is passed. If successful, the centroid is automatically recalculated after a cool-down interval. --- + ### `remove_documents_from_centroid` -`(centroid_id, document_ids, ignore_not_in_centroid=False)` +`(centroid_id, document_ids, ignore_not_in_centroid=false)` `-> RemoveDocumentsFromCentroidResponse` @@ -192,29 +335,76 @@ Raises `ECentroidDoesNotExist` if `centroid_id` refers to a nonexistent centroid Raises `EDocumentDoesNotExist` if any of the documents in `document_ids` does not exist. -Raises `EDocumentNotInCentroid` if any of the documents in `document_ids` is not currently associated with the centroid, unless `ignore_not_in_centroid=True` is passed. +Raises `EDocumentNotInCentroid` if any of the documents in `document_ids` is not currently associated with the centroid, unless `ignore_not_in_centroid=true` is passed. If successful, the centroid is automatically recalculated after a cool-down interval. --- -### `list_all_centroids` -`()` +### `list_all_documents_for_centroid` -`-> ListCentroidsResponse(centroids: list)` +`(centroid_id)` -Lists the IDs of all centroids existing on the server. +`-> ListCentroidDocumentsResponse(documents: list)` -This command has no error conditions. +Lists IDs of all documents associated with the given centroid. + +Raises `ECentroidDoesNotExist` if `centroid_id` refers to a nonexistent centroid. --- -### `list_all_documents` +### `list_centroid_document_range` -`()` +`(centroid_id, offset, count)` -`-> ListDocumentsResponse(documents: list)` +`-> ListCentroidDocumentsResponse(documents: list)` -Lists the IDs of all documents existing on the server. +Lists a range of IDs of documents associated with the given centroid. With keys sorted alphabetically, skips the first `offset` entries and returns up to `count` entries after that point. -This command has no error conditions. +Raises `ECentroidDoesNotExist` if `centroid_id` refers to a nonexistent centroid. + +--- +### `list_centroid_document_range_from_id` + +`(centroid_id, document_id, count)` + +`-> ListCentroidDocumentsResponse(documents: list)` + + + +Lists a range of IDs of documents associated with the given centroid. With keys sorted alphabetically, skips to `document_id` and then continues to return up to `count` total entries. This count includes the starting `document_id`. + +A missing `document_id` is not an error condition for this command. If `document_id` is not found, iteration will start from the ID of the next associated document located after it alphabetically. + +Raises `ECentroidDoesNotExist` if `centroid_id` refers to a nonexistent centroid. + +--- + +## Synchronization +### `join_centroid` + +`(centroid_id)` + +`-> JoinCentroidResponse(id: string, recalculated: bool)` + +Ensures a centroid is up to date before proceeding. +The server automatically recalculates centroids as documents are added and removed. `join_centroid` provides a way to synchronize with that process. The specific behavior is: + +- If the centroid is up to date, returns immediately. +- If an update job is currently in progress, returns once that job has completed. +- If the centroid is not up to date and no job is executing (because of the cool-off period), immediately starts the update and returns once it is complete. + +The `recalculated` property of the returned `JoinCentroidResponse` indicates whether a recalculation was actually performed. + +Raises `ECentroidDoesNotExist` if `centroid_id` refers to a nonexistent centroid. + +--- +### `multi_join_centroids` + +`(centroid_ids)` + +`-> MultiJoinCentroidsResponse(ids: list, recalculated: list)` + +Like `join_centroid`, but runs against multiple centroids in a single request. + +Raises `ECentroidDoesNotExist` if any of the `centroid_ids` refers to a nonexistent centroid.