Skip to content

Commit e6c4775

Browse files
JackieTien97JackieTien97
authored
Add Claude Code project config and refine .gitignore (#17458)
1 parent d06de8a commit e6c4775

3 files changed

Lines changed: 202 additions & 3 deletions

File tree

‎.claude/settings.json‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
{
2+
"hooks": {
3+
"PostToolUse": [
4+
{
5+
"matcher": "Write|Edit",
6+
"hooks": [
7+
{
8+
"type": "command",
9+
"command": "jq -r '.tool_input.file_path // .tool_response.filePath' | { read -r f; echo \"$f\" | grep -q '\\.java$' && mvn spotless:apply -f \"$(git rev-parse --show-toplevel)/pom.xml\" -DspotlessFiles=\"$(echo \"$f\" | sed 's/[.[\\\\/^$|?*+(){}]/\\\\&/g')\" -q || true; }",
10+
"timeout": 30,
11+
"statusMessage": "Running spotless format..."
12+
}
13+
]
14+
}
15+
]
16+
}
17+
}

‎.gitignore‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -128,6 +128,8 @@ iotdb-core/tsfile/src/main/antlr4/org/apache/tsfile/parser/gen/
128128
# Relational Grammar ANTLR
129129
iotdb-core/relational-grammar/src/main/antlr4/org/apache/iotdb/db/relational/grammar/sql/.antlr/
130130

131-
.claude/
132-
CLAUDE.md
133-
.worktreeinclude
131+
# Claude Code
132+
.claude/settings.local.json
133+
.claude/todos/
134+
.claude/worktrees/
135+
.claude/scheduled_tasks.json

‎CLAUDE.md‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
<!--
2+
3+
Licensed to the Apache Software Foundation (ASF) under one
4+
or more contributor license agreements. See the NOTICE file
5+
distributed with this work for additional information
6+
regarding copyright ownership. The ASF licenses this file
7+
to you under the Apache License, Version 2.0 (the
8+
"License"); you may not use this file except in compliance
9+
with the License. You may obtain a copy of the License at
10+
11+
http://www.apache.org/licenses/LICENSE-2.0
12+
13+
Unless required by applicable law or agreed to in writing,
14+
software distributed under the License is distributed on an
15+
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16+
KIND, either express or implied. See the License for the
17+
specific language governing permissions and limitations
18+
under the License.
19+
20+
-->
21+
22+
# CLAUDE.md
23+
24+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
25+
26+
## Project Overview
27+
28+
Apache IoTDB is a time series database for IoT data. It uses a distributed architecture with ConfigNodes (metadata/coordination) and DataNodes (storage/query). Data is stored in TsFile columnar format (separate repo: https://github.com/apache/tsfile). Current version is 2.0.7-SNAPSHOT.
29+
30+
## Build Commands
31+
32+
```bash
33+
# Full build (skip tests)
34+
mvn clean package -pl distribution -am -DskipTests
35+
36+
# Build a specific module (e.g., datanode)
37+
mvn clean package -pl iotdb-core/datanode -am -DskipTests
38+
39+
# Run unit tests for a specific module
40+
mvn clean test -pl iotdb-core/datanode
41+
42+
# Run a single test class
43+
mvn clean test -pl iotdb-core/datanode -Dtest=ClassName
44+
45+
# Run a single test method
46+
mvn clean test -pl iotdb-core/datanode -Dtest=ClassName#methodName
47+
48+
# Format code (requires JDK 17+; auto-skipped on JDK <17)
49+
mvn spotless:apply
50+
51+
# Format code in integration-test module
52+
mvn spotless:apply -P with-integration-tests
53+
54+
# Check formatting without applying
55+
mvn spotless:check
56+
```
57+
58+
## Integration Tests
59+
60+
Integration tests live in `integration-test/` (not included in default build). They require the `with-integration-tests` profile:
61+
62+
```bash
63+
# Build template-node first (needed once, or after code changes)
64+
mvn clean package -DskipTests -pl integration-test -am -P with-integration-tests
65+
66+
# Run tree-model ITs (simple: 1 ConfigNode + 1 DataNode)
67+
mvn clean verify -DskipUTs -pl integration-test -am -P with-integration-tests
68+
69+
# Run tree-model ITs (cluster: 1 ConfigNode + 3 DataNodes)
70+
mvn clean verify -DskipUTs -pl integration-test -am -PClusterIT -P with-integration-tests
71+
72+
# Run table-model ITs (simple)
73+
mvn clean verify -DskipUTs -pl integration-test -am -PTableSimpleIT -P with-integration-tests
74+
75+
# Run table-model ITs (cluster)
76+
mvn clean verify -DskipUTs -pl integration-test -am -PTableClusterIT -P with-integration-tests
77+
78+
# Run a single IT class (tree-model simple, 1C1D)
79+
mvn clean verify -DskipUTs -Dit.test=ClassName -DfailIfNoTests=false -Dfailsafe.failIfNoSpecifiedTests=false -pl integration-test -am -P with-integration-tests
80+
81+
# Run a single IT class (tree-model cluster, 1C3D)
82+
mvn clean verify -DskipUTs -Dit.test=ClassName -DfailIfNoTests=false -Dfailsafe.failIfNoSpecifiedTests=false -pl integration-test -am -PClusterIT -P with-integration-tests
83+
84+
# Run a single IT class (table-model simple, 1C1D)
85+
mvn clean verify -DskipUTs -Dit.test=ClassName -DfailIfNoTests=false -Dfailsafe.failIfNoSpecifiedTests=false -pl integration-test -am -PTableSimpleIT -P with-integration-tests
86+
87+
# Run a single IT class (table-model cluster, 1C3D)
88+
mvn clean verify -DskipUTs -Dit.test=ClassName -DfailIfNoTests=false -Dfailsafe.failIfNoSpecifiedTests=false -pl integration-test -am -PTableClusterIT -P with-integration-tests
89+
90+
# Run a single test method within an IT class (use ClassName#methodName)
91+
mvn clean verify -DskipUTs -Dit.test=ClassName#methodName -DfailIfNoTests=false -Dfailsafe.failIfNoSpecifiedTests=false -pl integration-test -am -PTableSimpleIT -P with-integration-tests
92+
```
93+
94+
When verifying a new feature, only run the specific IT classes/methods that were added or modified in the current branch — do not run all ITs.
95+
96+
To run integration tests from IntelliJ: enable the `with-integration-tests` profile in Maven sidebar, then run test cases directly.
97+
98+
## Code Style
99+
100+
- **Apache License header**: Every new file committed to the repository MUST include the Apache License 2.0 header. Use the comment syntax appropriate for the file type (e.g., `<!-- -->` for `.md`, `/* */` for `.java`, `#` for `.properties`/`.py`). JSON files are exempt (no comment syntax). Refer to existing files in the repo for the exact format.
101+
- **Spotless** with Google Java Format (GOOGLE style). Import order: `org.apache.iotdb`, blank, `javax`, `java`, static.
102+
- **Checkstyle** is also configured (see `checkstyle.xml` at project root).
103+
- Java source/target level is 1.8 (compiled with `maven.compiler.release=8` on JDK 9+).
104+
105+
## Architecture
106+
107+
### Node Types
108+
109+
- **ConfigNode** (`iotdb-core/confignode`): Manages cluster metadata, schema regions, data regions, partition tables. Coordinates via Ratis consensus.
110+
- **DataNode** (`iotdb-core/datanode`): Handles data storage, query execution, and client connections. The main server component.
111+
- **AINode** (`iotdb-core/ainode`): Python-based node for AI/ML inference tasks.
112+
113+
### Dual Data Model
114+
115+
IoTDB supports two data models operating on the same storage:
116+
- **Tree model**: Traditional IoT hierarchy (e.g., `root.ln.wf01.wt01.temperature`). SQL uses path-based addressing.
117+
- **Table model** (relational): SQL table semantics. Grammar lives in `iotdb-core/relational-grammar/`. Query plan code under `queryengine/plan/relational/`.
118+
119+
### Key DataNode Subsystems (`iotdb-core/datanode`)
120+
121+
- **queryengine**: SQL parsing, planning, optimization, and execution.
122+
- `plan/parser/` - ANTLR-based SQL parser
123+
- `plan/statement/` - AST statement nodes
124+
- `plan/planner/` - Logical and physical planning (tree model: `TreeModelPlanner`, table model: under `plan/relational/`)
125+
- `plan/optimization/` - Query optimization rules
126+
- `execution/operator/` - Physical operators (volcano-style iterator model)
127+
- `execution/exchange/` - Inter-node data exchange
128+
- `execution/fragment/` - Distributed query fragment management
129+
- **storageengine**: Write path, memtable, flush, WAL, compaction, TsFile management.
130+
- `dataregion/` - DataRegion lifecycle, memtable, flush, compaction
131+
- `dataregion/wal/` - Write-ahead log
132+
- `buffer/` - Memory buffer management
133+
- **schemaengine**: Schema (timeseries metadata) management.
134+
- **pipe**: Data sync/replication framework (source -> processor -> sink pipeline).
135+
- **consensus**: DataNode-side consensus integration.
136+
- **subscription**: Client subscription service for streaming data changes.
137+
138+
### Consensus (`iotdb-core/consensus`)
139+
140+
Pluggable consensus protocols: Simple (single-node), Ratis (Raft-based), IoT Consensus (optimized for IoT writes). Factory pattern via `ConsensusFactory`.
141+
142+
### Protocol Layer (`iotdb-protocol/`)
143+
144+
Thrift IDL definitions for RPC between nodes. Generated sources are produced automatically during build. Sub-modules: `thrift-commons`, `thrift-confignode`, `thrift-datanode`, `thrift-consensus`, `thrift-ainode`.
145+
146+
### Client Libraries (`iotdb-client/`)
147+
148+
- `session/` - Java Session API (primary client interface)
149+
- `jdbc/` - JDBC driver
150+
- `cli/` - Command-line client
151+
- `client-cpp/`, `client-go/`, `client-py/` - Multi-language clients
152+
- `service-rpc/` - Shared Thrift service definitions
153+
154+
### API Layer (`iotdb-api/`)
155+
156+
Extension point interfaces: `udf-api` (user-defined functions), `trigger-api` (event triggers), `pipe-api` (data sync plugins), `external-api`, `external-service-api`.
157+
158+
## IDE Setup
159+
160+
After `mvn package`, right-click the root project in IntelliJ and choose "Maven -> Reload Project" to add generated source roots (Thrift and ANTLR).
161+
162+
Generated source directories that need to be on the source path:
163+
- `**/target/generated-sources/thrift`
164+
- `**/target/generated-sources/antlr4`
165+
166+
## Common Pitfalls
167+
168+
### Build
169+
170+
- **Missing Thrift compiler**: The local machine may not have the `thrift` binary installed. Running `mvn clean package -pl <module> -am -DskipTests` will fail at the `iotdb-thrift` module. **Workaround**: To verify your changes compile, use `mvn compile -pl <module>` (without `-am` or `clean`) to leverage existing target caches.
171+
- **Pre-existing compilation errors in unrelated modules**: The datanode module may have pre-existing compile errors in other subsystems (e.g., pipe, copyto) that cause `mvn clean test -pl iotdb-core/datanode -Dtest=XxxTest` to fail during compilation. **Workaround**: First run `mvn compile -pl iotdb-core/datanode` to confirm your changed files compile successfully. If the errors are in files you did not modify, they are pre-existing and do not affect your changes.
172+
173+
### Code Style
174+
175+
- **Always run `mvn spotless:apply` after editing Java files**: Spotless runs `spotless:check` automatically during the `compile` phase. Format violations cause an immediate BUILD FAILURE. Make it a habit to run `mvn spotless:apply -pl <module>` right after editing, not at the end. For files under `integration-test/`, add `-P with-integration-tests`.
176+
- **Gson version compatibility**: `JsonObject.isEmpty()` / `JsonArray.isEmpty()` may not be available in the Gson version used by this project. Use `size() > 0` instead and add a comment explaining why.
177+
178+
## Git Commit
179+
180+
- Do NOT add `Co-Authored-By` trailer to commit messages.

0 commit comments

Comments
 (0)