Database Operations

/**
 * Retrieve a database by ID
 * @param args - Database retrieval parameters
 * @returns Promise resolving to database object
 */
databases.retrieve(args: GetDatabaseParameters): Promise<GetDatabaseResponse>;

interface GetDatabaseParameters {
  /** ID of the database to retrieve */
  database_id: string;
}

type GetDatabaseResponse = DatabaseObjectResponse;

// Get database schema and metadata
const database = await notion.databases.retrieve({
  database_id: "database-id-here",
});

console.log(database.title); // Database title
console.log(database.properties); // Property schema

/**
 * Create a new database
 * @param args - Database creation parameters
 * @returns Promise resolving to created database
 */
databases.create(args: CreateDatabaseParameters): Promise<CreateDatabaseResponse>;

interface CreateDatabaseParameters {
  /** Parent page for the database */
  parent: {
    type: "page_id";
    page_id: string;
  };
  /** Database title */
  title?: RichTextItemResponse[];
  /** Database properties schema */
  properties: Record<string, PropertySchema>;
  /** Database icon */
  icon?: {
    type: "emoji";
    emoji: string;
  } | {
    type: "external";
    external: { url: string };
  } | {
    type: "file";
    file: { url: string; expiry_time: string };
  };
  /** Database cover image */
  cover?: {
    type: "external";
    external: { url: string };
  } | {
    type: "file";
    file: { url: string; expiry_time: string };
  };
  /** Database description */
  description?: RichTextItemResponse[];
  /** Whether database is inline */
  is_inline?: boolean;
}

type CreateDatabaseResponse = DatabaseObjectResponse;

// Create a task database
const database = await notion.databases.create({
  parent: { type: "page_id", page_id: "parent-page-id" },
  title: [{ text: { content: "Task Database" } }],
  properties: {
    Name: {
      title: {},
    },
    Status: {
      select: {
        options: [
          { name: "Not started", color: "gray" },
          { name: "In progress", color: "yellow" },
          { name: "Complete", color: "green" },
        ],
      },
    },
    Priority: {
      number: {
        format: "number",
      },
    },
    "Due Date": {
      date: {},
    },
    Assignee: {
      people: {},
    },
  },
});

// Create database with cover and description
const database = await notion.databases.create({
  parent: { type: "page_id", page_id: "parent-id" },
  title: [{ text: { content: "Project Tracker" } }],
  description: [{ text: { content: "Track project progress and milestones" } }],
  icon: { type: "emoji", emoji: "📊" },
  cover: {
    type: "external",
    external: { url: "https://example.com/cover.jpg" },
  },
  properties: {
    "Project Name": { title: {} },
    Progress: {
      number: { format: "percent" },
    },
  },
});

/**
 * Update a database's schema and metadata
 * @param args - Database update parameters
 * @returns Promise resolving to updated database
 */
databases.update(args: UpdateDatabaseParameters): Promise<UpdateDatabaseResponse>;

interface UpdateDatabaseParameters {
  /** ID of the database to update */
  database_id: string;
  /** Updated database title */
  title?: RichTextItemResponse[];
  /** Updated database description */
  description?: RichTextItemResponse[];
  /** Updated database properties schema */
  properties?: Record<string, PropertySchema | null>;
  /** Updated database icon */
  icon?: {
    type: "emoji";
    emoji: string;
  } | {
    type: "external";
    external: { url: string };
  } | {
    type: "file";
    file: { url: string; expiry_time: string };
  } | null;
  /** Updated database cover */
  cover?: {
    type: "external";
    external: { url: string };
  } | {
    type: "file";
    file: { url: string; expiry_time: string };
  } | null;
  /** Archive the database */
  archived?: boolean;
}

type UpdateDatabaseResponse = DatabaseObjectResponse;

// Update database title and description
const updatedDatabase = await notion.databases.update({
  database_id: "database-id",
  title: [{ text: { content: "Updated Task Database" } }],
  description: [{ text: { content: "Updated description" } }],
});

// Add new property to database
const updatedDatabase = await notion.databases.update({
  database_id: "database-id",
  properties: {
    "New Property": {
      rich_text: {},
    },
  },
});

// Remove property from database
const updatedDatabase = await notion.databases.update({
  database_id: "database-id",
  properties: {
    "Old Property": null, // Remove property
  },
});

// Update database icon
const updatedDatabase = await notion.databases.update({
  database_id: "database-id",
  icon: {
    type: "emoji",
    emoji: "🗂️",
  },
});

interface DatabaseObjectResponse {
  object: "database";
  id: string;
  created_time: string;
  created_by: PartialUserObjectResponse;
  last_edited_time: string;
  last_edited_by: PartialUserObjectResponse;
  title: RichTextItemResponse[];
  description: RichTextItemResponse[];
  icon?: {
    type: "emoji";
    emoji: string;
  } | {
    type: "external";
    external: { url: string };
  } | {
    type: "file";
    file: { url: string; expiry_time: string };
  };
  cover?: {
    type: "external";
    external: { url: string };
  } | {
    type: "file";
    file: { url: string; expiry_time: string };
  };
  properties: Record<string, PropertySchema>;
  parent: {
    type: "page_id";
    page_id: string;
  } | {
    type: "workspace";
    workspace: true;
  };
  url: string;
  archived: boolean;
  is_inline: boolean;
  public_url?: string;
}

interface PartialDatabaseObjectResponse {
  object: "database";
  id: string;
}

type PropertySchema = 
  | { type: "title"; title: Record<string, never> }
  | { type: "rich_text"; rich_text: Record<string, never> }
  | { type: "number"; number: { format: "number" | "number_with_commas" | "percent" | "dollar" | "canadian_dollar" | "euro" | "pound" | "yen" | "ruble" | "rupee" | "won" | "yuan" | "real" | "lira" | "rupiah" | "franc" | "hong_kong_dollar" | "new_zealand_dollar" | "krona" | "norwegian_krone" | "mexican_peso" | "rand" | "new_taiwan_dollar" | "danish_krone" | "zloty" | "baht" | "forint" | "koruna" | "shekel" | "chilean_peso" | "philippine_peso" | "dirham" | "colombian_peso" | "riyal" | "ringgit" | "leu" | "argentine_peso" | "uruguayan_peso" } }
  | { type: "select"; select: { options: { name: string; color: string }[] } }
  | { type: "multi_select"; multi_select: { options: { name: string; color: string }[] } }
  | { type: "date"; date: Record<string, never> }
  | { type: "people"; people: Record<string, never> }
  | { type: "files"; files: Record<string, never> }
  | { type: "checkbox"; checkbox: Record<string, never> }
  | { type: "url"; url: Record<string, never> }
  | { type: "email"; email: Record<string, never> }
  | { type: "phone_number"; phone_number: Record<string, never> }
  | { type: "formula"; formula: { expression: string } }
  | { type: "relation"; relation: { database_id: string; synced_property_name?: string; synced_property_id?: string } }
  | { type: "rollup"; rollup: { relation_property_name: string; relation_property_id: string; rollup_property_name: string; rollup_property_id: string; function: "count" | "count_values" | "empty" | "not_empty" | "unique" | "show_unique" | "percent_empty" | "percent_not_empty" | "sum" | "average" | "median" | "min" | "max" | "range" | "earliest_date" | "latest_date" | "date_range" | "checked" | "unchecked" | "percent_checked" | "percent_unchecked" | "count_per_group" | "percent_per_group" | "show_original" } }
  | { type: "created_time"; created_time: Record<string, never> }
  | { type: "created_by"; created_by: Record<string, never> }
  | { type: "last_edited_time"; last_edited_time: Record<string, never> }
  | { type: "last_edited_by"; last_edited_by: Record<string, never> }
  | { type: "status"; status: { options: { name: string; color: string }[]; groups: { name: string; color: string; option_ids: string[] }[] } }
  | { type: "unique_id"; unique_id: { prefix?: string } }
  | { type: "verification"; verification: Record<string, never> };