doc(server): sync server-core with master - #488
Conversation
Rebuild the config option tables from CoreOptions, AuthOptions, RoleElectionOptions, ServerOptions, RocksDBOptions and HstoreOptions so every key, default and allowed value matches master: drop the keys that no longer exist, add the 60+ that were missing, and correct wrong defaults such as raft.path, raft.rpc_timeout, gremlinserver.max_route and three RocksDB block cache flags. Also refresh the plugin SPI listings, the TinkerPop feature tables, the vertex and edge id length limits, the CUSTOMIZE_UUID id strategy and the edge label multi-link behaviour, and fix broken Gremlin step links. Mark meta.endpoints as declared but unread: no code reads ServerOptions.META_ENDPOINTS, and GraphManager.initMetaManager builds the meta connection from pd.peers instead.
d6f464a to
b8b2037
Compare
bitflicker64
left a comment
There was a problem hiding this comment.
Blocking: no. Summary: Well-sourced documentation sync; I checked every config row on both the en and cn pages against the option declarations at apache/hugegraph@36811483a, and every default, allowed-value list and removal holds up, as do the interface listings, TinkerPop feature flags, id-length limits and the confirm_message value. Three minor items inline, one of which is the single k8s.algorithms row whose default column holds a Java symbol instead of a value. Evidence: extracted all 282 option declarations (278 distinct keys) from CoreOptions, ServerOptions, AuthOptions, RoleElectionOptions, RpcOptions, RocksDBOptions, HbaseOptions and HstoreOptions, then diffed key, default and description against the 321 rows on each page; confirmed the six keys dropped from the en page (seven on cn, including the misspelt snowflake.datecenter_id) have no occurrence in the tree; and read BackendStore, GraphSerializer, HugeGraphPlugin, RocksDBStoreProvider, HugeFeatures, BytesBuffer, HugeVertex/HugeEdge, EdgeLabelBuilder, IdStrategy, AnalyzerFactory, SerializerFactory, BackendProviderFactory, GraphsAPI and GraphManager.initMetaManager directly. CI on b8b2037: eight checks green, publish skipped.
| | k8s.operator_template | ./conf/operator-template.yaml | The path of operator container template. | | ||
| | k8s.quota_template | ./conf/resource-quota-template.yaml | The path of resource quota template. | | ||
| | search.text_analyzer | ikanalyzer | Choose a text analyzer for searching the vertex/edge properties, available type are [ansj, hanlp, smartcn, jieba, jcseg, mmseg4j, ikanalyzer]. The shipped graph templates set `jieba`. If use 'ikanalyzer', need download jar from 'https://github.com/apache/hugegraph-doc/raw/ik_binary/dist/server/ikanalyzer-2012_u6.jar' to lib directory | | ||
| | search.text_analyzer_mode | smart | Specify the mode for the text analyzer, the available mode of analyzer are {ansj: [BaseAnalysis, IndexAnalysis, ToAnalysis, NlpAnalysis], hanlp: [standard, nlp, index, nShort, shortest, speed], smartcn: [], jieba: [SEARCH, INDEX], jcseg: [Simple, Complex], mmseg4j: [Simple, Complex, MaxWord], ikanalyzer: [smart, max_word]}. | |
There was a problem hiding this comment.
🧹 The search.text_analyzer row above gained "The shipped graph templates set jieba", but this row still shows only the option default smart, with no note that both shipped templates set search.text_analyzer_mode=INDEX:
hugegraph-server/hugegraph-dist/src/assembly/static/conf/graphs/hugegraph.properties
hugegraph-server/hugegraph-dist/src/assembly/static/conf/graphs/hstore.properties.template
That matters here because smart is not a legal mode for the analyzer those same templates select:
// hugegraph-core/.../analyzer/JiebaAnalyzer.java:35
public static final List<String> SUPPORT_MODES = ImmutableList.of("SEARCH", "INDEX");The description column does spell out jieba: [SEARCH, INDEX], so an attentive reader will not be caught out; it is the default column and the missing template note that are out of step with the row above. Could you append "The shipped graph templates set INDEX." to the description, matching the sibling row? Same row on content/cn/docs/config/config-option.md:184.
| > | server.default_oltp_k8s_namespace | hugegraph-server | The default oltp namespace for HugeGraph default graph space. | | ||
| > | server.default_olap_k8s_namespace | hugegraph-computer-system | The default olap namespace for HugeGraph default graph space. | | ||
| > | k8s.internal_algorithm | [page-rank, degree-centrality, wcc, triangle-count, rings, rings-with-filter, betweenness-centrality, closeness-centrality, lpa, links, kcore, louvain, clustering-coefficient, ppr, subgraph-match] | The names of the built-in k8s algorithms. | | ||
| > | k8s.algorithms | See `ServerOptions.K8S_ALGORITHMS` | The `name:paramsClass` mapping of the built-in k8s algorithms. | |
There was a problem hiding this comment.
🧹 Two gaps in this block, which the PR description says was "expanded to the full k8s/PD-service set from ServerOptions":
-
k8s.internal_algorithm_image_urlis missing (ServerOptions.java:687-693, default"", description "K8s internal algorithm image url"). Comparing this page's key set against all 278 distinct option keys in the eight holders at36811483a, it is the only one left undocumented, on both the en and cn pages. -
This row is the only one in the file whose default column holds a Java symbol rather than a value.
K8S_ALGORITHMSis aConfigListOptiondefaulting to onename:paramsClassentry per name ink8s.internal_algorithm, startingpage-rank:org.apache.hugegraph.computer.algorithm.centrality.pagerank.PageRankParams. The block is already collapsed, so listing them is fine; otherwise "onename:paramsClassentry per algorithm ink8s.internal_algorithm" would say more than a symbol the reader cannot open.
Same block on content/cn/docs/config/config-option.md:325.
| - How to delete all data from a graph | ||
|
|
||
| An administrator can call `DELETE /graphspaces/{graphspace}/graphs/{graph}/clear`. The request must include the `confirm_message` required by the source code; see the [Graph API](../clients/restful-api/graphs) for the exact format. This operation removes schemas, vertices, edges, and indexes. | ||
| An administrator can call `DELETE /graphspaces/{graphspace}/graphs/{graph}/clear?confirm_message=I'm sure to delete all data`. The `confirm_message` query parameter must match that value exactly, otherwise the request is rejected. See the [Graph API](../clients/restful-api/graphs) for details. This operation removes schemas, vertices, edges, and indexes. |
There was a problem hiding this comment.
🧹 Spelling out the confirmation string is a real improvement over the old "see the Graph API" pointer, and the value matches GraphsAPI.CONFIRM_CLEAR. But the URL as written carries five raw spaces and an apostrophe:
DELETE /graphspaces/{graphspace}/graphs/{graph}/clear?confirm_message=I'm sure to delete all data
Pasted into curl that either breaks on the quote or truncates at the first space, and the server check is an exact match:
// api/profile/GraphsAPI.java:604
E.checkArgument(CONFIRM_CLEAR.equals(message), "Please take the message: %s", CONFIRM_CLEAR);so a partially-transmitted value just fails. Could you show the percent-encoded form in the URL, ?confirm_message=I%27m%20sure%20to%20delete%20all%20data, and keep the plain sentence in the surrounding prose? Same line on content/cn/docs/guides/faq.md:78.
imbajin
left a comment
There was a problem hiding this comment.
中文部分与源码保持一致且表述清晰,评分 9.2/10,按规则可直接合并。
Syncs the server-core docs (en and cn) against
apache/hugegraphmaster at36811483a(1.7.0).Every default and allowed value below was read from the Options class or the conf template the
server actually reads, not from the previous doc text.
store.schema,store.system,raft.endpoint,raft.use_snapshotdocumented as graph options, but no such keys existhugegraph-server/hugegraph-core/.../config/CoreOptions.java(no such options; absent from the whole tree)raft.group_peerslisted under the graph properties file127.0.0.1:8090hugegraph-server/hugegraph-api/.../config/ServerOptions.java:585raft.pathdefault./raft-log./raftlogCoreOptions.java:108raft.rpc_timeoutdefault60000and no unit60, described as secondsCoreOptions.java:229raft.rpc_threadsdefault80max(CPUs * 2, 80)CoreOptions.java:213oltp.concurrent_threadsdefault10max(10, CPUs / 2)CoreOptions.java:403computer.configdefault/conf/computer.yaml./conf/computer.yamlCoreOptions.java:630storedescribed as "the database name like Cassandra Keyspace"CoreOptions.java:64backenddefaultrocksdb,serializerdefaultbinaryand its allowed values listed cassandra/mysqlmemoryandtext, with a note that the shipped graph templates setrocksdb/hstoreandbinary; serializer values are text/binary/binaryscatter plus backend-registered onesCoreOptions.java:49,78,backend/serializer/SerializerFactory.java,hugegraph-dist/src/assembly/static/conf/graphs/hugegraph.properties:22-27search.text_analyzerand_modelisted awordanalyzer and its modesanalyzer/AnalyzerFactory.java:36-53,CoreOptions.java:603,613serializer.buffer_max_capacity,schema.init_template,schema.index_rebuild_using_pushdown,query.trust_index,query.max_indexes_available,query.dedup_option,oltp.query_batch_size,oltp.query_batch_avg_degree_ratio,oltp.query_batch_expect_degree,task.schedule_period,task.retry,k8s.operator_template,k8s.quota_template,pd.peers,graphspace,alias.graph.id,graph.read_mode, the fourmemory.*keys and the five missingraft.snapshot*/raft.install_snapshot_rpc_timeoutkeysCoreOptions.java:85,701,534,56,709,717,429,437,446,281,326,637,644,650,681,688,694,656-674,139-160,237conf/graphs/hugegraph.properties:59-61server.iddescribed as "used for license verification"ServerOptions.java(SERVER_ID)gremlinserver.max_routedefault82 * CPUsServerOptions.java(GREMLIN_SERVER_MAX_ROUTE)auth.cache_expiredescribed as "expiration time of vertex cache"hugegraph-server/hugegraph-core/.../config/AuthOptions.java(AUTH_CACHE_EXPIRE)graphs.enable_dynamic_create_drop,init_store.enabled,server.role_election,server.node_id,server.node_role,server.graphspace,server.service_id,server.path_graphspace,server.start_ignore_single_graph_error,server.event_hub_threads,restserver.task_threads,white_ip.statusServerOptions.javaserver.role.*keyshugegraph-server/hugegraph-core/.../masterelection/RoleElectionOptions.javacluster,metrics.data_to_pd,meta.use_ca,meta.ca,meta.client_ca,meta.client_key, plushstore.partition_countandhstore.shard_countfrom the graph fileServerOptions.java,hugegraph-server/hugegraph-hstore/.../HstoreOptions.java:27-38meta.endpointswas listed with defaulthttp://127.0.0.1:2379and a description implying it configures the metadata connectionpd.peers, which the meta connection is actually built fromhugegraph-server/hugegraph-api/.../config/ServerOptions.java:139-144(declared; the only hit forMETA_ENDPOINTSormeta.endpointsin the tree),hugegraph-server/hugegraph-api/.../core/GraphManager.java:527-541(initMetaManagerreadsPD_PEERS)ServerOptions.javarocksdb.cache_index_and_filter_blocks,rocksdb.pin_l0_filter_and_index_blocks_in_cache,rocksdb.optimize_filters_for_hitsdocumented asfalsetruehugegraph-server/hugegraph-rocksdb/.../RocksDBOptions.java:614,623,662SNAPPY_COMPRESSION,NO_COMPRESSION)snappy,none,[none, none, snappy, snappy, snappy, snappy, snappy]RocksDBOptions.java:141,151,161rocksdb.option_pathandrocksdb.open_httpdocumented (ToplingDB)RocksDBOptionsor anywhere else in the tree at this commitRocksDBOptions.javarocksdb.block_size,index_type,format_version,bytes_per_sync,row_cache_capacity,memtable_*,partition_filters_and_indexes,prefix_extractor_n_bytes, and the rest)RocksDBOptions.javahbase.krb5_confdefaultetc/krb5.conf,hbase.truncate_timeoutmissing/etc/krb5.conf, addedhbase.truncate_timeout=30hugegraph-server/hugegraph-hbase/.../HbaseOptions.javaarthas.disabledCommandsServerOptions.java(ARTHAS_DISABLED_COMMANDS)rpc.serializationrpc.serialization=hessian2to bothhugegraph-commons/hugegraph-rpc/.../config/RpcOptions.javamaxContentLength,maxChunkSize,maxHeaderSize,resultIterationBatchSize,ssl.enabledhugegraph-dist/src/assembly/static/conf/gremlin-server.yaml:117-127RocksDBStoreProvidersample usednewSchemaStore(String),newGraphStore(String)andversion()returning1.0HugeConfig,newSystemStoreadded,driverVersion()returns1.11hugegraph-rocksdb/.../RocksDBStoreProvider.javaBackendStorelisting was missing nine methods and hadclear()instead ofclear(boolean)hugegraph-core/.../backend/store/BackendStore.javaGraphSerializerlisting was missingwriteOlapVertexandreadEdgespublicmodifiers dropped to match the interfaceshugegraph-core/.../backend/serializer/GraphSerializer.javaRocksDBOptionssample hadrocksdb-datapaths and the oldgraph/*data_disks keysrocksdb-data/data,rocksdb-data/waland the currentg/*key listRocksDBOptions.java(DATA_PATH, WAL_PATH, DATA_DISKS)DemoPluginsample omittedsupportsMinVersion/supportsMaxVersion, which the loader requireshugegraph-dist/.../dist/RegisterUtil.java(registerPlugins)analyzer/AnalyzerFactory.java:36-53Id max length is 128, edge id 32768, index id 128The max length of vertex id is 16384/edge id is 65536; index ids over 32 bytes are hashedbackend/serializer/BytesBuffer.java:63-64,76,structure/HugeVertex.java:186-195,structure/HugeEdge.java:158-163EdgeLabeldoes not support connecting multiple pairs ofVertexLabels"link()accumulates pairs;sourceLabel()/targetLabel()are deprecated single-pair methodsschema/builder/EdgeLabelBuilder.java:411-418,schema/EdgeLabel.java:203-212,254-257?confirm_message=I'm sure to delete all datahugegraph-api/.../api/profile/GraphsAPI.java:79,589-603CUSTOMIZE_UUIDwas absentCUSTOMIZE_UUIDand auseCustomizeUuidId()example addedtype/define/IdStrategy.java,schema/VertexLabel.java:122,schema/builder/VertexLabelBuilder.java:323content/cn/docs/guides/desgin-concept.mdbackend/store/BackendProviderFactory.java:44-45(ALLOWED_BACKENDS)UserSuppliedIds,StringIds,CustomIds,MultiProperties,DuplicateMultiPropertiesshown as falsestructure/HugeFeatures.java:116,136,240,250,256StringIdsandCustomIdsshown as false;UniformListValuesshown as falsestructure/HugeFeatures.java:116,136,349-356#add-stepfor and,#addedge-stepfor count and path) and two URLs had stray dots (apac.he.org,docs/c.urrent)Vrow is now labelled "vertex steps"battledrow added with itstimeproperty2.1 Graph Schemablockschema/builder/EdgeLabelBuilder.java:411-418where(is(neq(pluto))).values('name')Verified with no change needed:
guides/architectural.md(backend list already matchesALLOWED_BACKENDS, all internal links resolve) and the six frozen benchmark reports underperformance/(all images and links resolve; numbers untouched).