dosubot[bot] commented on issue #668:
URL:
https://github.com/apache/incubator-hugegraph-toolchain/issues/668#issuecomment-2934750298
<!-- Answer -->
关于 HugeGraph Java 客户端 K-neighbor API
中集合属性（set/list）的谓词过滤逻辑，这里给你详细举例说明，并结合实际运行结果和底层实现逻辑：
---
### 1. 过滤逻辑说明
- `P.within(...)`：判断集合属性中是否“存在任意一个”指定值，只要集合里有一个元素匹配就会返回该数据。例如，`P.within("A",
"B")` 会匹配 `tags` 包含 "A" 或 "B" 的顶点。
- `P.contains(...)`：判断集合属性中是否“包含某个具体值”。如果集合中有该元素，则返回该数据。例如，`P.contains("A")`
只会匹配 `tags` 包含 "A" 的顶点。
---
### 2. Java 客户端 K-neighbor API 示例
假设你的 schema 里有一个 set 类型的属性 `tags`，你想查找 tags 包含 "A" 或 "B" 的邻居：
```java
import org.apache.hugegraph.api.traverser.KneighborAPI;
import org.apache.hugegraph.structure.traverser.KneighborRequest;
import org.apache.hugegraph.structure.traverser.Steps;
import java.util.HashMap;
import java.util.Map;
// 构建属性过滤条件
Map<String, Object> properties = new HashMap<>();
properties.put("tags", "P.within(\"A\", \"B\")"); // 或
properties.put("tags", "P.contains(\"A\")")
// 构建 StepEntity
Steps.StepEntity vertexStep = new Steps.StepEntity("your_vertex_label",
properties);
// 构建 KneighborRequest
KneighborRequest.Builder builder = KneighborRequest.builder();
builder.source("your_vertex_id");
builder.steps().direction(Direction.BOTH).vertexSteps(vertexStep);
builder.maxDepth(1);
builder.withVertex(true);
KneighborRequest request = builder.build();
// 发起 K-neighbor 查询
KneighborAPI kneighborAPI = new KneighborAPI(client, "graphSpace", "graph");
Kneighbor result = kneighborAPI.post(request);
```
---
### 3. 实际运行结果举例
以 Gremlin 查询为例，假设有如下顶点：
- 顶点A: tags = ["A", "C"]
- 顶点B: tags = ["B"]
- 顶点C: tags = ["C"]
- 使用 `P.within("A", "B")` 查询，返回顶点A和B（只要集合中有A或B即可）。
- 使用 `P.contains("A")` 查询，只返回顶点A（集合中必须有A）。
相关 Gremlin 查询示例（底层原理一致）：
```groovy
g.V().hasLabel('your_vertex_label').has('tags', ConditionP.contains('A'))
// 返回所有 tags 集合中包含 "A" 的顶点
g.V().hasLabel('your_vertex_label').has('tags', ConditionP.contains('B'))
// 返回所有 tags 集合中包含 "B" 的顶点
```
实际测试代码和断言可参考 HugeGraph
的单元测试：[VertexCoreTest.java](https://github.com/apache/incubator-hugegraph/blob/337dc86567834acd717a2240a79fef2815d4bb6f/hugegraph-server/hugegraph-test/src/main/java/org/apache/hugegraph/core/VertexCoreTest.java)
和
[EdgeCoreTest.java](https://github.com/apache/incubator-hugegraph/blob/337dc86567834acd717a2240a79fef2815d4bb6f/hugegraph-server/hugegraph-test/src/main/java/org/apache/hugegraph/core/EdgeCoreTest.java)。
---
### 4. 注意事项
- schema 必须将属性定义为 set 或 list 类型，否则谓词不会生效。
- `P.within(...)` 更适合“集合中包含任意一个”的场景，`P.contains(...)` 适合“集合中包含某个具体值”。
- 如果 `P.contains(...)` 过滤掉所有数据，常见原因是属性类型不对、数据不匹配或谓词拼写有误。
---
### 5. 参考文档与源码
- [KneighborRequest/StepEntity
源码](https://github.com/apache/incubator-hugegraph-toolchain/blob/50a839469b1ad779115e371d0df378116638e9e1/hugegraph-client/src/main/java/org/apache/hugegraph/structure/traverser/KneighborRequest.java)
-
[集合属性谓词解析实现](https://github.com/apache/incubator-hugegraph/blob/337dc86567834acd717a2240a79fef2815d4bb6f/hugegraph-server/hugegraph-core/src/main/java/org/apache/hugegraph/traversal/optimize/TraversalUtil.java)
-
[集合属性谓词测试用例](https://github.com/apache/incubator-hugegraph/blob/337dc86567834acd717a2240a79fef2815d4bb6f/hugegraph-server/hugegraph-test/src/main/java/org/apache/hugegraph/core/VertexCoreTest.java)
---
如需更复杂的谓词或多层过滤，直接在 `properties` 里用字符串表达式即可，后端会自动解析并执行。
<!-- Dosu Comment Footer -->
*To reply, just mention my name [@dosu](https://go.dosu.dev/dosubot).*
---
<sup>How did I do?
[Good](https://app.dosu.dev/response-feedback/bbf5d3f7-c9f3-4afc-ac01-a35a678bb5c7?feedback_type=great_response)
|
[Irrelevant](https://app.dosu.dev/response-feedback/bbf5d3f7-c9f3-4afc-ac01-a35a678bb5c7?feedback_type=irrelevant_answer)
|
[Incorrect](https://app.dosu.dev/response-feedback/bbf5d3f7-c9f3-4afc-ac01-a35a678bb5c7?feedback_type=incorrect_sources)
|
[Verbose](https://app.dosu.dev/response-feedback/bbf5d3f7-c9f3-4afc-ac01-a35a678bb5c7?feedback_type=too_verbose)
|
[Hallucination](https://app.dosu.dev/response-feedback/bbf5d3f7-c9f3-4afc-ac01-a35a678bb5c7?feedback_type=hallucination)
| [Report
🐛](https://app.dosu.dev/response-feedback/bbf5d3f7-c9f3-4afc-ac01-a35a678bb5c7?feedback_type=bug_report)
|
[Other](https://app.dosu.dev/response-feedback/bbf5d3f7-c9f3-4afc-ac01-a35a678bb5c7?feedback_type=other)</sup> [](https://go.dosu.dev/discord-bot) [!
[Share on
X](https://img.shields.io/badge/X-share-black)](https://twitter.com/intent/tweet?text=%40dosu_ai%20helped%20me%20solve%20this%20issue!&url=https%3A//github.com/apache/incubator-hugegraph-toolchain/issues/668)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
