ibm_watson 0.7.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 2b27fbff4d3847691ce67cabe41fcc8b232a1d671631126cfeedf501674d6725
4
- data.tar.gz: a61caeff375e304b1a31e7b32f61f0638728dd75e8691d65d3a3bde225b80b50
3
+ metadata.gz: a7ab67f5e1862edec369814a6922632805dfd6168754a3f5fe4f308c2563ede1
4
+ data.tar.gz: 9439f61e848fb0683c0c82b15c7146611504b2d31b33dc897ebc149bab870e58
5
5
  SHA512:
6
- metadata.gz: 89cd8d4c28251093e95a4fcfe4537f481da27c6689391be06822b62d1522bbaaf2e36fc11c28f51d3b44c4da9d6f308b0129cd0b52fe3994bf5377af0a8172a0
7
- data.tar.gz: c1e2f944f9bf0db887c374468c038fef0e3224859fae24be6202974e7f6eebc4673f9ae232382d89a70dee2929fe3eb5e5548c074583c0995f5636a46dac0e1d
6
+ metadata.gz: 278793e0322df1edfe1d5aa1ba33e89b2142e0d9c02ee0d4f2243452e7c0731cbf427d3ee24b8f3aadd8993bc5a0a181c52fffa4f1c8197d66b22560f4424bd6
7
+ data.tar.gz: 3fde12cf25463d7368a9febb161ea311d9ff61f099e86a2368f71eda35f8006755c10e206bac8181c9fc332dbf3f97a3f784c9eebcb8f05649ee5e56fa84d8e8
@@ -100,7 +100,8 @@ module IBMWatson
100
100
  # instance. An attempt to create another environment results in an error.
101
101
  # @param name [String] Name that identifies the environment.
102
102
  # @param description [String] Description of the environment.
103
- # @param size [String] Size of the environment.
103
+ # @param size [String] Size of the environment. In the Lite plan the default and only accepted value is
104
+ # `LT`, in all other plans the default is `S`.
104
105
  # @return [DetailedResponse] A `DetailedResponse` object representing the response.
105
106
  def create_environment(name:, description: nil, size: nil)
106
107
  raise ArgumentError("name must be provided") if name.nil?
@@ -176,15 +177,18 @@ module IBMWatson
176
177
  end
177
178
 
178
179
  ##
179
- # @!method update_environment(environment_id:, name: nil, description: nil)
180
+ # @!method update_environment(environment_id:, name: nil, description: nil, size: nil)
180
181
  # Update an environment.
181
182
  # Updates an environment. The environment's **name** and **description** parameters
182
183
  # can be changed. You must specify a **name** for the environment.
183
184
  # @param environment_id [String] The ID of the environment.
184
185
  # @param name [String] Name that identifies the environment.
185
186
  # @param description [String] Description of the environment.
187
+ # @param size [String] Size that the environment should be increased to. Environment size cannot be
188
+ # modified when using a Lite plan. Environment size can only increased and not
189
+ # decreased.
186
190
  # @return [DetailedResponse] A `DetailedResponse` object representing the response.
187
- def update_environment(environment_id:, name: nil, description: nil)
191
+ def update_environment(environment_id:, name: nil, description: nil, size: nil)
188
192
  raise ArgumentError("environment_id must be provided") if environment_id.nil?
189
193
 
190
194
  headers = {
@@ -194,7 +198,8 @@ module IBMWatson
194
198
  }
195
199
  data = {
196
200
  "name" => name,
197
- "description" => description
201
+ "description" => description,
202
+ "size" => size
198
203
  }
199
204
  method_url = "/v1/environments/%s" % [ERB::Util.url_encode(environment_id)]
200
205
  response = request(
@@ -1044,16 +1049,17 @@ module IBMWatson
1044
1049
  #########################
1045
1050
 
1046
1051
  ##
1047
- # @!method query(environment_id:, collection_id:, filter: nil, query: nil, natural_language_query: nil, passages: nil, aggregation: nil, count: nil, return_fields: nil, offset: nil, sort: nil, highlight: nil, passages_fields: nil, passages_count: nil, passages_characters: nil, deduplicate: nil, deduplicate_field: nil, similar: nil, similar_document_ids: nil, similar_fields: nil, logging_opt_out: nil)
1048
- # Query your collection.
1049
- # After your content is uploaded and enriched by the Discovery service, you can
1050
- # build queries to search your content. For details, see the [Discovery service
1052
+ # @!method query(environment_id:, collection_id:, filter: nil, query: nil, natural_language_query: nil, passages: nil, aggregation: nil, count: nil, return_fields: nil, offset: nil, sort: nil, highlight: nil, passages_fields: nil, passages_count: nil, passages_characters: nil, deduplicate: nil, deduplicate_field: nil, collection_ids: nil, similar: nil, similar_document_ids: nil, similar_fields: nil, bias: nil, logging_opt_out: nil)
1053
+ # Long collection queries.
1054
+ # Complex queries might be too long for a standard method query. By using this
1055
+ # method, you can construct longer queries. However, these queries may take longer
1056
+ # to complete than the standard method. For details, see the [Discovery service
1051
1057
  # documentation](https://console.bluemix.net/docs/services/discovery/using.html).
1052
1058
  # @param environment_id [String] The ID of the environment.
1053
1059
  # @param collection_id [String] The ID of the collection.
1054
- # @param filter [String] A cacheable query that limits the documents returned to exclude any documents that
1055
- # don't mention the query content. Filter searches are better for metadata type
1056
- # searches and when you are trying to get a sense of concepts in the data set.
1060
+ # @param filter [String] A cacheable query that excludes documents that don't mention the query content.
1061
+ # Filter searches are better for metadata-type searches and for assessing the
1062
+ # concepts in the data set.
1057
1063
  # @param query [String] A query search returns all documents in your data set with full enrichments and
1058
1064
  # full text, but with the most relevant documents listed first. Use a query search
1059
1065
  # when you want to find the most relevant search results. You cannot use
@@ -1062,27 +1068,25 @@ module IBMWatson
1062
1068
  # data and natural language understanding. You cannot use **natural_language_query**
1063
1069
  # and **query** at the same time.
1064
1070
  # @param passages [Boolean] A passages query that returns the most relevant passages from the results.
1065
- # @param aggregation [String] An aggregation search uses combinations of filters and query search to return an
1066
- # exact answer. Aggregations are useful for building applications, because you can
1067
- # use them to build lists, tables, and time series. For a full list of possible
1068
- # aggregrations, see the Query reference.
1071
+ # @param aggregation [String] An aggregation search that returns an exact answer by combining query search with
1072
+ # filters. Useful for applications to build lists, tables, and time series. For a
1073
+ # full list of possible aggregations, see the Query reference.
1069
1074
  # @param count [Fixnum] Number of results to return.
1070
- # @param return_fields [Array[String]] A comma separated list of the portion of the document hierarchy to return.
1075
+ # @param return_fields [String] A comma-separated list of the portion of the document hierarchy to return.
1071
1076
  # @param offset [Fixnum] The number of query results to skip at the beginning. For example, if the total
1072
- # number of results that are returned is 10, and the offset is 8, it returns the
1073
- # last two results.
1074
- # @param sort [Array[String]] A comma separated list of fields in the document to sort on. You can optionally
1077
+ # number of results that are returned is 10 and the offset is 8, it returns the last
1078
+ # two results.
1079
+ # @param sort [String] A comma-separated list of fields in the document to sort on. You can optionally
1075
1080
  # specify a sort direction by prefixing the field with `-` for descending or `+` for
1076
- # ascending. Ascending is the default sort direction if no prefix is specified.
1077
- # @param highlight [Boolean] When true a highlight field is returned for each result which contains the fields
1078
- # that match the query with `<em></em>` tags around the matching query terms.
1079
- # Defaults to false.
1080
- # @param passages_fields [Array[String]] A comma-separated list of fields that passages are drawn from. If this parameter
1081
+ # ascending. Ascending is the default sort direction if no prefix is specified. This
1082
+ # parameter cannot be used in the same query as the **bias** parameter.
1083
+ # @param highlight [Boolean] When true, a highlight field is returned for each result which contains the fields
1084
+ # which match the query with `<em></em>` tags around the matching query terms.
1085
+ # @param passages_fields [String] A comma-separated list of fields that passages are drawn from. If this parameter
1081
1086
  # not specified, then all top-level fields are included.
1082
1087
  # @param passages_count [Fixnum] The maximum number of passages to return. The search returns fewer passages if the
1083
1088
  # requested total is not found. The default is `10`. The maximum is `100`.
1084
- # @param passages_characters [Fixnum] The approximate number of characters that any one passage will have. The default
1085
- # is `400`. The minimum is `50`. The maximum is `2000`.
1089
+ # @param passages_characters [Fixnum] The approximate number of characters that any one passage will have.
1086
1090
  # @param deduplicate [Boolean] When `true` and used with a Watson Discovery News collection, duplicate results
1087
1091
  # (based on the contents of the **title** field) are removed. Duplicate comparison
1088
1092
  # is limited to the current query only; **offset** is not considered. This parameter
@@ -1090,21 +1094,28 @@ module IBMWatson
1090
1094
  # @param deduplicate_field [String] When specified, duplicate results based on the field specified are removed from
1091
1095
  # the returned results. Duplicate comparison is limited to the current query only,
1092
1096
  # **offset** is not considered. This parameter is currently Beta functionality.
1097
+ # @param collection_ids [String] A comma-separated list of collection IDs to be queried against. Required when
1098
+ # querying multiple collections, invalid when performing a single collection query.
1093
1099
  # @param similar [Boolean] When `true`, results are returned based on their similarity to the document IDs
1094
1100
  # specified in the **similar.document_ids** parameter.
1095
- # @param similar_document_ids [Array[String]] A comma-separated list of document IDs that will be used to find similar
1096
- # documents.
1101
+ # @param similar_document_ids [String] A comma-separated list of document IDs to find similar documents.
1097
1102
  #
1098
- # **Note:** If the **natural_language_query** parameter is also specified, it will
1099
- # be used to expand the scope of the document similarity search to include the
1100
- # natural language query. Other query parameters, such as **filter** and **query**
1101
- # are subsequently applied and reduce the query scope.
1102
- # @param similar_fields [Array[String]] A comma-separated list of field names that will be used as a basis for comparison
1103
- # to identify similar documents. If not specified, the entire document is used for
1103
+ # **Tip:** Include the **natural_language_query** parameter to expand the scope of
1104
+ # the document similarity search with the natural language query. Other query
1105
+ # parameters, such as **filter** and **query**, are subsequently applied and reduce
1106
+ # the scope.
1107
+ # @param similar_fields [String] A comma-separated list of field names that are used as a basis for comparison to
1108
+ # identify similar documents. If not specified, the entire document is used for
1104
1109
  # comparison.
1110
+ # @param bias [String] Field which the returned results will be biased against. The specified field must
1111
+ # be either a **date** or **number** format. When a **date** type field is specified
1112
+ # returned results are biased towards field values closer to the current date. When
1113
+ # a **number** type field is specified, returned results are biased towards higher
1114
+ # field values. This parameter cannot be used in the same query as the **sort**
1115
+ # parameter.
1105
1116
  # @param logging_opt_out [Boolean] If `true`, queries are not stored in the Discovery **Logs** endpoint.
1106
1117
  # @return [DetailedResponse] A `DetailedResponse` object representing the response.
1107
- def query(environment_id:, collection_id:, filter: nil, query: nil, natural_language_query: nil, passages: nil, aggregation: nil, count: nil, return_fields: nil, offset: nil, sort: nil, highlight: nil, passages_fields: nil, passages_count: nil, passages_characters: nil, deduplicate: nil, deduplicate_field: nil, similar: nil, similar_document_ids: nil, similar_fields: nil, logging_opt_out: nil)
1118
+ def query(environment_id:, collection_id:, filter: nil, query: nil, natural_language_query: nil, passages: nil, aggregation: nil, count: nil, return_fields: nil, offset: nil, sort: nil, highlight: nil, passages_fields: nil, passages_count: nil, passages_characters: nil, deduplicate: nil, deduplicate_field: nil, collection_ids: nil, similar: nil, similar_document_ids: nil, similar_fields: nil, bias: nil, logging_opt_out: nil)
1108
1119
  raise ArgumentError("environment_id must be provided") if environment_id.nil?
1109
1120
 
1110
1121
  raise ArgumentError("collection_id must be provided") if collection_id.nil?
@@ -1113,32 +1124,37 @@ module IBMWatson
1113
1124
  "X-Watson-Logging-Opt-Out" => logging_opt_out
1114
1125
  }
1115
1126
  params = {
1116
- "version" => @version,
1127
+ "version" => @version
1128
+ }
1129
+ data = {
1117
1130
  "filter" => filter,
1118
1131
  "query" => query,
1119
1132
  "natural_language_query" => natural_language_query,
1120
1133
  "passages" => passages,
1121
1134
  "aggregation" => aggregation,
1122
1135
  "count" => count,
1123
- "return" => return_fields.to_a,
1136
+ "return" => return_fields,
1124
1137
  "offset" => offset,
1125
- "sort" => sort.to_a,
1138
+ "sort" => sort,
1126
1139
  "highlight" => highlight,
1127
- "passages.fields" => passages_fields.to_a,
1140
+ "passages.fields" => passages_fields,
1128
1141
  "passages.count" => passages_count,
1129
1142
  "passages.characters" => passages_characters,
1130
1143
  "deduplicate" => deduplicate,
1131
1144
  "deduplicate.field" => deduplicate_field,
1145
+ "collection_ids" => collection_ids,
1132
1146
  "similar" => similar,
1133
- "similar.document_ids" => similar_document_ids.to_a,
1134
- "similar.fields" => similar_fields.to_a
1147
+ "similar.document_ids" => similar_document_ids,
1148
+ "similar.fields" => similar_fields,
1149
+ "bias" => bias
1135
1150
  }
1136
1151
  method_url = "/v1/environments/%s/collections/%s/query" % [ERB::Util.url_encode(environment_id), ERB::Util.url_encode(collection_id)]
1137
1152
  response = request(
1138
- method: "GET",
1153
+ method: "POST",
1139
1154
  url: method_url,
1140
1155
  headers: headers,
1141
1156
  params: params,
1157
+ json: data,
1142
1158
  accept_json: true
1143
1159
  )
1144
1160
  response
@@ -1154,9 +1170,9 @@ module IBMWatson
1154
1170
  # more details on the query language.
1155
1171
  # @param environment_id [String] The ID of the environment.
1156
1172
  # @param collection_id [String] The ID of the collection.
1157
- # @param filter [String] A cacheable query that limits the documents returned to exclude any documents that
1158
- # don't mention the query content. Filter searches are better for metadata type
1159
- # searches and when you are trying to get a sense of concepts in the data set.
1173
+ # @param filter [String] A cacheable query that excludes documents that don't mention the query content.
1174
+ # Filter searches are better for metadata-type searches and for assessing the
1175
+ # concepts in the data set.
1160
1176
  # @param query [String] A query search returns all documents in your data set with full enrichments and
1161
1177
  # full text, but with the most relevant documents listed first. Use a query search
1162
1178
  # when you want to find the most relevant search results. You cannot use
@@ -1165,41 +1181,37 @@ module IBMWatson
1165
1181
  # data and natural language understanding. You cannot use **natural_language_query**
1166
1182
  # and **query** at the same time.
1167
1183
  # @param passages [Boolean] A passages query that returns the most relevant passages from the results.
1168
- # @param aggregation [String] An aggregation search uses combinations of filters and query search to return an
1169
- # exact answer. Aggregations are useful for building applications, because you can
1170
- # use them to build lists, tables, and time series. For a full list of possible
1171
- # aggregrations, see the Query reference.
1184
+ # @param aggregation [String] An aggregation search that returns an exact answer by combining query search with
1185
+ # filters. Useful for applications to build lists, tables, and time series. For a
1186
+ # full list of possible aggregations, see the Query reference.
1172
1187
  # @param count [Fixnum] Number of results to return.
1173
- # @param return_fields [Array[String]] A comma separated list of the portion of the document hierarchy to return.
1188
+ # @param return_fields [Array[String]] A comma-separated list of the portion of the document hierarchy to return.
1174
1189
  # @param offset [Fixnum] The number of query results to skip at the beginning. For example, if the total
1175
- # number of results that are returned is 10, and the offset is 8, it returns the
1176
- # last two results.
1177
- # @param sort [Array[String]] A comma separated list of fields in the document to sort on. You can optionally
1190
+ # number of results that are returned is 10 and the offset is 8, it returns the last
1191
+ # two results.
1192
+ # @param sort [Array[String]] A comma-separated list of fields in the document to sort on. You can optionally
1178
1193
  # specify a sort direction by prefixing the field with `-` for descending or `+` for
1179
1194
  # ascending. Ascending is the default sort direction if no prefix is specified.
1180
- # @param highlight [Boolean] When true a highlight field is returned for each result which contains the fields
1181
- # that match the query with `<em></em>` tags around the matching query terms.
1182
- # Defaults to false.
1195
+ # @param highlight [Boolean] When true, a highlight field is returned for each result which contains the fields
1196
+ # which match the query with `<em></em>` tags around the matching query terms.
1183
1197
  # @param passages_fields [Array[String]] A comma-separated list of fields that passages are drawn from. If this parameter
1184
1198
  # not specified, then all top-level fields are included.
1185
1199
  # @param passages_count [Fixnum] The maximum number of passages to return. The search returns fewer passages if the
1186
- # requested total is not found. The default is `10`. The maximum is `100`.
1187
- # @param passages_characters [Fixnum] The approximate number of characters that any one passage will have. The default
1188
- # is `400`. The minimum is `50`. The maximum is `2000`.
1200
+ # requested total is not found.
1201
+ # @param passages_characters [Fixnum] The approximate number of characters that any one passage will have.
1189
1202
  # @param deduplicate_field [String] When specified, duplicate results based on the field specified are removed from
1190
1203
  # the returned results. Duplicate comparison is limited to the current query only,
1191
1204
  # **offset** is not considered. This parameter is currently Beta functionality.
1192
1205
  # @param similar [Boolean] When `true`, results are returned based on their similarity to the document IDs
1193
1206
  # specified in the **similar.document_ids** parameter.
1194
- # @param similar_document_ids [Array[String]] A comma-separated list of document IDs that will be used to find similar
1195
- # documents.
1207
+ # @param similar_document_ids [Array[String]] A comma-separated list of document IDs to find similar documents.
1196
1208
  #
1197
- # **Note:** If the **natural_language_query** parameter is also specified, it will
1198
- # be used to expand the scope of the document similarity search to include the
1199
- # natural language query. Other query parameters, such as **filter** and **query**
1200
- # are subsequently applied and reduce the query scope.
1201
- # @param similar_fields [Array[String]] A comma-separated list of field names that will be used as a basis for comparison
1202
- # to identify similar documents. If not specified, the entire document is used for
1209
+ # **Tip:** Include the **natural_language_query** parameter to expand the scope of
1210
+ # the document similarity search with the natural language query. Other query
1211
+ # parameters, such as **filter** and **query**, are subsequently applied and reduce
1212
+ # the scope.
1213
+ # @param similar_fields [Array[String]] A comma-separated list of field names that are used as a basis for comparison to
1214
+ # identify similar documents. If not specified, the entire document is used for
1203
1215
  # comparison.
1204
1216
  # @return [DetailedResponse] A `DetailedResponse` object representing the response.
1205
1217
  def query_notices(environment_id:, collection_id:, filter: nil, query: nil, natural_language_query: nil, passages: nil, aggregation: nil, count: nil, return_fields: nil, offset: nil, sort: nil, highlight: nil, passages_fields: nil, passages_count: nil, passages_characters: nil, deduplicate_field: nil, similar: nil, similar_document_ids: nil, similar_fields: nil)
@@ -1241,16 +1253,16 @@ module IBMWatson
1241
1253
  end
1242
1254
 
1243
1255
  ##
1244
- # @!method federated_query(environment_id:, collection_ids:, filter: nil, query: nil, natural_language_query: nil, aggregation: nil, count: nil, return_fields: nil, offset: nil, sort: nil, highlight: nil, deduplicate: nil, deduplicate_field: nil, similar: nil, similar_document_ids: nil, similar_fields: nil, passages: nil, passages_fields: nil, passages_count: nil, passages_characters: nil)
1245
- # Query documents in multiple collections.
1246
- # See the [Discovery service
1247
- # documentation](https://console.bluemix.net/docs/services/discovery/using.html) for
1248
- # more details.
1256
+ # @!method federated_query(environment_id:, filter: nil, query: nil, natural_language_query: nil, passages: nil, aggregation: nil, count: nil, return_fields: nil, offset: nil, sort: nil, highlight: nil, passages_fields: nil, passages_count: nil, passages_characters: nil, deduplicate: nil, deduplicate_field: nil, collection_ids: nil, similar: nil, similar_document_ids: nil, similar_fields: nil, bias: nil, logging_opt_out: nil)
1257
+ # Long environment queries.
1258
+ # Complex queries might be too long for a standard method query. By using this
1259
+ # method, you can construct longer queries. However, these queries may take longer
1260
+ # to complete than the standard method. For details, see the [Discovery service
1261
+ # documentation](https://console.bluemix.net/docs/services/discovery/using.html).
1249
1262
  # @param environment_id [String] The ID of the environment.
1250
- # @param collection_ids [Array[String]] A comma-separated list of collection IDs to be queried against.
1251
- # @param filter [String] A cacheable query that limits the documents returned to exclude any documents that
1252
- # don't mention the query content. Filter searches are better for metadata type
1253
- # searches and when you are trying to get a sense of concepts in the data set.
1263
+ # @param filter [String] A cacheable query that excludes documents that don't mention the query content.
1264
+ # Filter searches are better for metadata-type searches and for assessing the
1265
+ # concepts in the data set.
1254
1266
  # @param query [String] A query search returns all documents in your data set with full enrichments and
1255
1267
  # full text, but with the most relevant documents listed first. Use a query search
1256
1268
  # when you want to find the most relevant search results. You cannot use
@@ -1258,21 +1270,26 @@ module IBMWatson
1258
1270
  # @param natural_language_query [String] A natural language query that returns relevant documents by utilizing training
1259
1271
  # data and natural language understanding. You cannot use **natural_language_query**
1260
1272
  # and **query** at the same time.
1261
- # @param aggregation [String] An aggregation search uses combinations of filters and query search to return an
1262
- # exact answer. Aggregations are useful for building applications, because you can
1263
- # use them to build lists, tables, and time series. For a full list of possible
1264
- # aggregrations, see the Query reference.
1273
+ # @param passages [Boolean] A passages query that returns the most relevant passages from the results.
1274
+ # @param aggregation [String] An aggregation search that returns an exact answer by combining query search with
1275
+ # filters. Useful for applications to build lists, tables, and time series. For a
1276
+ # full list of possible aggregations, see the Query reference.
1265
1277
  # @param count [Fixnum] Number of results to return.
1266
- # @param return_fields [Array[String]] A comma separated list of the portion of the document hierarchy to return.
1278
+ # @param return_fields [String] A comma-separated list of the portion of the document hierarchy to return.
1267
1279
  # @param offset [Fixnum] The number of query results to skip at the beginning. For example, if the total
1268
- # number of results that are returned is 10, and the offset is 8, it returns the
1269
- # last two results.
1270
- # @param sort [Array[String]] A comma separated list of fields in the document to sort on. You can optionally
1280
+ # number of results that are returned is 10 and the offset is 8, it returns the last
1281
+ # two results.
1282
+ # @param sort [String] A comma-separated list of fields in the document to sort on. You can optionally
1271
1283
  # specify a sort direction by prefixing the field with `-` for descending or `+` for
1272
- # ascending. Ascending is the default sort direction if no prefix is specified.
1273
- # @param highlight [Boolean] When true a highlight field is returned for each result which contains the fields
1274
- # that match the query with `<em></em>` tags around the matching query terms.
1275
- # Defaults to false.
1284
+ # ascending. Ascending is the default sort direction if no prefix is specified. This
1285
+ # parameter cannot be used in the same query as the **bias** parameter.
1286
+ # @param highlight [Boolean] When true, a highlight field is returned for each result which contains the fields
1287
+ # which match the query with `<em></em>` tags around the matching query terms.
1288
+ # @param passages_fields [String] A comma-separated list of fields that passages are drawn from. If this parameter
1289
+ # not specified, then all top-level fields are included.
1290
+ # @param passages_count [Fixnum] The maximum number of passages to return. The search returns fewer passages if the
1291
+ # requested total is not found. The default is `10`. The maximum is `100`.
1292
+ # @param passages_characters [Fixnum] The approximate number of characters that any one passage will have.
1276
1293
  # @param deduplicate [Boolean] When `true` and used with a Watson Discovery News collection, duplicate results
1277
1294
  # (based on the contents of the **title** field) are removed. Duplicate comparison
1278
1295
  # is limited to the current query only; **offset** is not considered. This parameter
@@ -1280,61 +1297,65 @@ module IBMWatson
1280
1297
  # @param deduplicate_field [String] When specified, duplicate results based on the field specified are removed from
1281
1298
  # the returned results. Duplicate comparison is limited to the current query only,
1282
1299
  # **offset** is not considered. This parameter is currently Beta functionality.
1300
+ # @param collection_ids [String] A comma-separated list of collection IDs to be queried against. Required when
1301
+ # querying multiple collections, invalid when performing a single collection query.
1283
1302
  # @param similar [Boolean] When `true`, results are returned based on their similarity to the document IDs
1284
1303
  # specified in the **similar.document_ids** parameter.
1285
- # @param similar_document_ids [Array[String]] A comma-separated list of document IDs that will be used to find similar
1286
- # documents.
1304
+ # @param similar_document_ids [String] A comma-separated list of document IDs to find similar documents.
1287
1305
  #
1288
- # **Note:** If the **natural_language_query** parameter is also specified, it will
1289
- # be used to expand the scope of the document similarity search to include the
1290
- # natural language query. Other query parameters, such as **filter** and **query**
1291
- # are subsequently applied and reduce the query scope.
1292
- # @param similar_fields [Array[String]] A comma-separated list of field names that will be used as a basis for comparison
1293
- # to identify similar documents. If not specified, the entire document is used for
1306
+ # **Tip:** Include the **natural_language_query** parameter to expand the scope of
1307
+ # the document similarity search with the natural language query. Other query
1308
+ # parameters, such as **filter** and **query**, are subsequently applied and reduce
1309
+ # the scope.
1310
+ # @param similar_fields [String] A comma-separated list of field names that are used as a basis for comparison to
1311
+ # identify similar documents. If not specified, the entire document is used for
1294
1312
  # comparison.
1295
- # @param passages [Boolean] A passages query that returns the most relevant passages from the results.
1296
- # @param passages_fields [Array[String]] A comma-separated list of fields that passages are drawn from. If this parameter
1297
- # not specified, then all top-level fields are included.
1298
- # @param passages_count [Fixnum] The maximum number of passages to return. The search returns fewer passages if the
1299
- # requested total is not found. The default is `10`. The maximum is `100`.
1300
- # @param passages_characters [Fixnum] The approximate number of characters that any one passage will have. The default
1301
- # is `400`. The minimum is `50`. The maximum is `2000`.
1313
+ # @param bias [String] Field which the returned results will be biased against. The specified field must
1314
+ # be either a **date** or **number** format. When a **date** type field is specified
1315
+ # returned results are biased towards field values closer to the current date. When
1316
+ # a **number** type field is specified, returned results are biased towards higher
1317
+ # field values. This parameter cannot be used in the same query as the **sort**
1318
+ # parameter.
1319
+ # @param logging_opt_out [Boolean] If `true`, queries are not stored in the Discovery **Logs** endpoint.
1302
1320
  # @return [DetailedResponse] A `DetailedResponse` object representing the response.
1303
- def federated_query(environment_id:, collection_ids:, filter: nil, query: nil, natural_language_query: nil, aggregation: nil, count: nil, return_fields: nil, offset: nil, sort: nil, highlight: nil, deduplicate: nil, deduplicate_field: nil, similar: nil, similar_document_ids: nil, similar_fields: nil, passages: nil, passages_fields: nil, passages_count: nil, passages_characters: nil)
1321
+ def federated_query(environment_id:, filter: nil, query: nil, natural_language_query: nil, passages: nil, aggregation: nil, count: nil, return_fields: nil, offset: nil, sort: nil, highlight: nil, passages_fields: nil, passages_count: nil, passages_characters: nil, deduplicate: nil, deduplicate_field: nil, collection_ids: nil, similar: nil, similar_document_ids: nil, similar_fields: nil, bias: nil, logging_opt_out: nil)
1304
1322
  raise ArgumentError("environment_id must be provided") if environment_id.nil?
1305
1323
 
1306
- raise ArgumentError("collection_ids must be provided") if collection_ids.nil?
1307
-
1308
1324
  headers = {
1325
+ "X-Watson-Logging-Opt-Out" => logging_opt_out
1309
1326
  }
1310
1327
  params = {
1311
- "version" => @version,
1312
- "collection_ids" => collection_ids.to_a,
1328
+ "version" => @version
1329
+ }
1330
+ data = {
1313
1331
  "filter" => filter,
1314
1332
  "query" => query,
1315
1333
  "natural_language_query" => natural_language_query,
1334
+ "passages" => passages,
1316
1335
  "aggregation" => aggregation,
1317
1336
  "count" => count,
1318
- "return" => return_fields.to_a,
1337
+ "return" => return_fields,
1319
1338
  "offset" => offset,
1320
- "sort" => sort.to_a,
1339
+ "sort" => sort,
1321
1340
  "highlight" => highlight,
1341
+ "passages.fields" => passages_fields,
1342
+ "passages.count" => passages_count,
1343
+ "passages.characters" => passages_characters,
1322
1344
  "deduplicate" => deduplicate,
1323
1345
  "deduplicate.field" => deduplicate_field,
1346
+ "collection_ids" => collection_ids,
1324
1347
  "similar" => similar,
1325
- "similar.document_ids" => similar_document_ids.to_a,
1326
- "similar.fields" => similar_fields.to_a,
1327
- "passages" => passages,
1328
- "passages.fields" => passages_fields.to_a,
1329
- "passages.count" => passages_count,
1330
- "passages.characters" => passages_characters
1348
+ "similar.document_ids" => similar_document_ids,
1349
+ "similar.fields" => similar_fields,
1350
+ "bias" => bias
1331
1351
  }
1332
1352
  method_url = "/v1/environments/%s/query" % [ERB::Util.url_encode(environment_id)]
1333
1353
  response = request(
1334
- method: "GET",
1354
+ method: "POST",
1335
1355
  url: method_url,
1336
1356
  headers: headers,
1337
1357
  params: params,
1358
+ json: data,
1338
1359
  accept_json: true
1339
1360
  )
1340
1361
  response
@@ -1350,9 +1371,9 @@ module IBMWatson
1350
1371
  # more details on the query language.
1351
1372
  # @param environment_id [String] The ID of the environment.
1352
1373
  # @param collection_ids [Array[String]] A comma-separated list of collection IDs to be queried against.
1353
- # @param filter [String] A cacheable query that limits the documents returned to exclude any documents that
1354
- # don't mention the query content. Filter searches are better for metadata type
1355
- # searches and when you are trying to get a sense of concepts in the data set.
1374
+ # @param filter [String] A cacheable query that excludes documents that don't mention the query content.
1375
+ # Filter searches are better for metadata-type searches and for assessing the
1376
+ # concepts in the data set.
1356
1377
  # @param query [String] A query search returns all documents in your data set with full enrichments and
1357
1378
  # full text, but with the most relevant documents listed first. Use a query search
1358
1379
  # when you want to find the most relevant search results. You cannot use
@@ -1360,35 +1381,32 @@ module IBMWatson
1360
1381
  # @param natural_language_query [String] A natural language query that returns relevant documents by utilizing training
1361
1382
  # data and natural language understanding. You cannot use **natural_language_query**
1362
1383
  # and **query** at the same time.
1363
- # @param aggregation [String] An aggregation search uses combinations of filters and query search to return an
1364
- # exact answer. Aggregations are useful for building applications, because you can
1365
- # use them to build lists, tables, and time series. For a full list of possible
1366
- # aggregrations, see the Query reference.
1384
+ # @param aggregation [String] An aggregation search that returns an exact answer by combining query search with
1385
+ # filters. Useful for applications to build lists, tables, and time series. For a
1386
+ # full list of possible aggregations, see the Query reference.
1367
1387
  # @param count [Fixnum] Number of results to return.
1368
- # @param return_fields [Array[String]] A comma separated list of the portion of the document hierarchy to return.
1388
+ # @param return_fields [Array[String]] A comma-separated list of the portion of the document hierarchy to return.
1369
1389
  # @param offset [Fixnum] The number of query results to skip at the beginning. For example, if the total
1370
- # number of results that are returned is 10, and the offset is 8, it returns the
1371
- # last two results.
1372
- # @param sort [Array[String]] A comma separated list of fields in the document to sort on. You can optionally
1390
+ # number of results that are returned is 10 and the offset is 8, it returns the last
1391
+ # two results.
1392
+ # @param sort [Array[String]] A comma-separated list of fields in the document to sort on. You can optionally
1373
1393
  # specify a sort direction by prefixing the field with `-` for descending or `+` for
1374
1394
  # ascending. Ascending is the default sort direction if no prefix is specified.
1375
- # @param highlight [Boolean] When true a highlight field is returned for each result which contains the fields
1376
- # that match the query with `<em></em>` tags around the matching query terms.
1377
- # Defaults to false.
1395
+ # @param highlight [Boolean] When true, a highlight field is returned for each result which contains the fields
1396
+ # which match the query with `<em></em>` tags around the matching query terms.
1378
1397
  # @param deduplicate_field [String] When specified, duplicate results based on the field specified are removed from
1379
1398
  # the returned results. Duplicate comparison is limited to the current query only,
1380
1399
  # **offset** is not considered. This parameter is currently Beta functionality.
1381
1400
  # @param similar [Boolean] When `true`, results are returned based on their similarity to the document IDs
1382
1401
  # specified in the **similar.document_ids** parameter.
1383
- # @param similar_document_ids [Array[String]] A comma-separated list of document IDs that will be used to find similar
1384
- # documents.
1402
+ # @param similar_document_ids [Array[String]] A comma-separated list of document IDs to find similar documents.
1385
1403
  #
1386
- # **Note:** If the **natural_language_query** parameter is also specified, it will
1387
- # be used to expand the scope of the document similarity search to include the
1388
- # natural language query. Other query parameters, such as **filter** and **query**
1389
- # are subsequently applied and reduce the query scope.
1390
- # @param similar_fields [Array[String]] A comma-separated list of field names that will be used as a basis for comparison
1391
- # to identify similar documents. If not specified, the entire document is used for
1404
+ # **Tip:** Include the **natural_language_query** parameter to expand the scope of
1405
+ # the document similarity search with the natural language query. Other query
1406
+ # parameters, such as **filter** and **query**, are subsequently applied and reduce
1407
+ # the scope.
1408
+ # @param similar_fields [Array[String]] A comma-separated list of field names that are used as a basis for comparison to
1409
+ # identify similar documents. If not specified, the entire document is used for
1392
1410
  # comparison.
1393
1411
  # @return [DetailedResponse] A `DetailedResponse` object representing the response.
1394
1412
  def federated_query_notices(environment_id:, collection_ids:, filter: nil, query: nil, natural_language_query: nil, aggregation: nil, count: nil, return_fields: nil, offset: nil, sort: nil, highlight: nil, deduplicate_field: nil, similar: nil, similar_document_ids: nil, similar_fields: nil)
@@ -1487,7 +1505,8 @@ module IBMWatson
1487
1505
  # your query would look for `London` with the context of `England`.
1488
1506
  # @param sort [String] The sorting method for the relationships, can be `score` or `frequency`.
1489
1507
  # `frequency` is the number of unique times each entity is identified. The default
1490
- # is `score`.
1508
+ # is `score`. This parameter cannot be used in the same query as the **bias**
1509
+ # parameter.
1491
1510
  # @param filter [QueryRelationsFilter] Filters to apply to the relationship query.
1492
1511
  # @param count [Fixnum] The number of results to return. The default is `10`. The maximum is `1000`.
1493
1512
  # @param evidence_count [Fixnum] The number of evidence items to return for each result. The default is `0`. The
@@ -1943,18 +1962,18 @@ module IBMWatson
1943
1962
  # Searches the query and event log to find query sessions that match the specified
1944
1963
  # criteria. Searching the **logs** endpoint uses the standard Discovery query syntax
1945
1964
  # for the parameters that are supported.
1946
- # @param filter [String] A cacheable query that limits the documents returned to exclude any documents that
1947
- # don't mention the query content. Filter searches are better for metadata type
1948
- # searches and when you are trying to get a sense of concepts in the data set.
1965
+ # @param filter [String] A cacheable query that excludes documents that don't mention the query content.
1966
+ # Filter searches are better for metadata-type searches and for assessing the
1967
+ # concepts in the data set.
1949
1968
  # @param query [String] A query search returns all documents in your data set with full enrichments and
1950
1969
  # full text, but with the most relevant documents listed first. Use a query search
1951
1970
  # when you want to find the most relevant search results. You cannot use
1952
1971
  # **natural_language_query** and **query** at the same time.
1953
1972
  # @param count [Fixnum] Number of results to return.
1954
1973
  # @param offset [Fixnum] The number of query results to skip at the beginning. For example, if the total
1955
- # number of results that are returned is 10, and the offset is 8, it returns the
1956
- # last two results.
1957
- # @param sort [Array[String]] A comma separated list of fields in the document to sort on. You can optionally
1974
+ # number of results that are returned is 10 and the offset is 8, it returns the last
1975
+ # two results.
1976
+ # @param sort [Array[String]] A comma-separated list of fields in the document to sort on. You can optionally
1958
1977
  # specify a sort direction by prefixing the field with `-` for descending or `+` for
1959
1978
  # ascending. Ascending is the default sort direction if no prefix is specified.
1960
1979
  # @return [DetailedResponse] A `DetailedResponse` object representing the response.