sqlite_graphrag/commands/
rename_entity.rs

1//! Handler for the `rename-entity` CLI subcommand.
2//!
3//! Renames an entity preserving all relationships and memory bindings.
4//! Only the `name` column in `entities` and the corresponding `vec_entities`
5//! row need updating because relationships use integer FK `entity_id`.
6
7use crate::entity_type::EntityType;
8use crate::errors::AppError;
9use crate::i18n::errors_msg;
10use crate::output::{self, OutputFormat};
11use crate::paths::AppPaths;
12use crate::storage::connection::open_rw;
13use crate::storage::entities;
14use rusqlite::params;
15use serde::Serialize;
16
17#[derive(clap::Args)]
18#[command(after_long_help = "EXAMPLES:\n  \
19    # Rename an entity\n  \
20    sqlite-graphrag rename-entity --name old-name --new-name new-name\n\n  \
21    # Rename with namespace\n  \
22    sqlite-graphrag rename-entity --name auth --new-name authentication --namespace my-project")]
23pub struct RenameEntityArgs {
24    /// Current entity name to rename.
25    #[arg(long, value_name = "NAME")]
26    pub name: String,
27    /// New name for the entity.
28    #[arg(long, value_name = "NEW_NAME")]
29    pub new_name: String,
30    #[arg(long)]
31    pub namespace: Option<String>,
32    #[arg(long, value_enum, default_value = "json")]
33    pub format: OutputFormat,
34    #[arg(long, hide = true, help = "No-op; JSON is always emitted on stdout")]
35    pub json: bool,
36    #[arg(long, env = "SQLITE_GRAPHRAG_DB_PATH")]
37    pub db: Option<String>,
38}
39
40#[derive(Serialize)]
41struct RenameEntityResponse {
42    action: String,
43    old_name: String,
44    new_name: String,
45    entity_id: i64,
46    namespace: String,
47    elapsed_ms: u64,
48}
49
50pub fn run(args: RenameEntityArgs) -> Result<(), AppError> {
51    let start = std::time::Instant::now();
52    let namespace = crate::namespace::resolve_namespace(args.namespace.as_deref())?;
53    let paths = AppPaths::resolve(args.db.as_deref())?;
54
55    crate::storage::connection::ensure_db_ready(&paths)?;
56
57    let mut conn = open_rw(&paths.db)?;
58
59    // Verify source entity exists and fetch its id and type.
60    let row: Option<(i64, EntityType)> = {
61        let mut stmt = conn
62            .prepare_cached("SELECT id, type FROM entities WHERE namespace = ?1 AND name = ?2")?;
63        match stmt.query_row(params![namespace, args.name], |r| {
64            Ok((r.get::<_, i64>(0)?, r.get::<_, EntityType>(1)?))
65        }) {
66            Ok(row) => Some(row),
67            Err(rusqlite::Error::QueryReturnedNoRows) => None,
68            Err(e) => return Err(AppError::Database(e)),
69        }
70    };
71    let (entity_id, entity_type) = row
72        .ok_or_else(|| AppError::NotFound(errors_msg::entity_not_found(&args.name, &namespace)))?;
73
74    entities::validate_entity_name(&args.new_name)?;
75
76    if args.name == args.new_name {
77        return Err(AppError::Validation(
78            "source and target entity names are identical".to_string(),
79        ));
80    }
81
82    // Ensure new name is not already taken in this namespace.
83    if entities::find_entity_id(&conn, &namespace, &args.new_name)?.is_some() {
84        return Err(AppError::Validation(format!(
85            "entity with name '{}' already exists in namespace '{}'",
86            args.new_name, namespace
87        )));
88    }
89
90    // Embed new name for vec_entities replacement.
91    let embedding = crate::daemon::embed_passage_or_local(&paths.models, &args.new_name)?;
92
93    let tx = conn.transaction_with_behavior(rusqlite::TransactionBehavior::Immediate)?;
94    tx.execute(
95        "UPDATE entities SET name = ?1, updated_at = unixepoch() WHERE id = ?2",
96        params![args.new_name, entity_id],
97    )?;
98    // vec0 does not support UPDATE — delete then insert.
99    tx.execute(
100        "DELETE FROM vec_entities WHERE entity_id = ?1",
101        params![entity_id],
102    )?;
103    let embedding_bytes = crate::embedder::f32_to_bytes(&embedding);
104    tx.execute(
105        "INSERT INTO vec_entities(entity_id, namespace, type, embedding, name)
106         VALUES (?1, ?2, ?3, ?4, ?5)",
107        params![
108            entity_id,
109            namespace,
110            entity_type,
111            &embedding_bytes,
112            args.new_name
113        ],
114    )?;
115    tx.commit()?;
116
117    conn.execute_batch("PRAGMA wal_checkpoint(TRUNCATE);")?;
118
119    let response = RenameEntityResponse {
120        action: "renamed".to_string(),
121        old_name: args.name,
122        new_name: args.new_name,
123        entity_id,
124        namespace: namespace.clone(),
125        elapsed_ms: start.elapsed().as_millis() as u64,
126    };
127
128    match args.format {
129        OutputFormat::Json => output::emit_json(&response)?,
130        OutputFormat::Text | OutputFormat::Markdown => {
131            output::emit_text(&format!(
132                "renamed entity: '{}' → '{}' [{}]",
133                response.old_name, response.new_name, response.namespace
134            ));
135        }
136    }
137
138    Ok(())
139}
140
141#[cfg(test)]
142mod tests {
143    use super::*;
144
145    #[test]
146    fn rename_entity_response_serializes_all_fields() {
147        let resp = RenameEntityResponse {
148            action: "renamed".to_string(),
149            old_name: "auth".to_string(),
150            new_name: "authentication".to_string(),
151            entity_id: 42,
152            namespace: "global".to_string(),
153            elapsed_ms: 7,
154        };
155        let json = serde_json::to_value(&resp).expect("serialization failed");
156        assert_eq!(json["action"], "renamed");
157        assert_eq!(json["old_name"], "auth");
158        assert_eq!(json["new_name"], "authentication");
159        assert_eq!(json["entity_id"], 42);
160        assert_eq!(json["namespace"], "global");
161        assert!(json["elapsed_ms"].is_number());
162    }
163
164    #[test]
165    fn rename_entity_response_action_is_renamed() {
166        let resp = RenameEntityResponse {
167            action: "renamed".to_string(),
168            old_name: "x".to_string(),
169            new_name: "y".to_string(),
170            entity_id: 1,
171            namespace: "ns".to_string(),
172            elapsed_ms: 1,
173        };
174        assert_eq!(resp.action, "renamed");
175    }
176
177    #[test]
178    fn rename_entity_response_entity_id_preserved() {
179        let resp = RenameEntityResponse {
180            action: "renamed".to_string(),
181            old_name: "old".to_string(),
182            new_name: "new".to_string(),
183            entity_id: 999,
184            namespace: "test-ns".to_string(),
185            elapsed_ms: 5,
186        };
187        let json = serde_json::to_value(&resp).expect("serialization failed");
188        assert_eq!(json["entity_id"], 999);
189    }
190
191    #[test]
192    fn rejects_rename_entity_to_same_name() {
193        use crate::errors::AppError;
194        let err = AppError::Validation("source and target entity names are identical".to_string());
195        assert_eq!(err.exit_code(), 1);
196        assert!(err.to_string().contains("identical"));
197    }
198
199    #[test]
200    fn rename_entity_response_namespace_reflected() {
201        let resp = RenameEntityResponse {
202            action: "renamed".to_string(),
203            old_name: "a".to_string(),
204            new_name: "b".to_string(),
205            entity_id: 10,
206            namespace: "my-project".to_string(),
207            elapsed_ms: 2,
208        };
209        let json = serde_json::to_value(&resp).expect("serialization failed");
210        assert_eq!(json["namespace"], "my-project");
211    }
212}
sqlite_graphrag/commands/rename_entity.rs

sqlite_graphrag/commands/
rename_entity.rs
