get_column_examples

Instructions

Implementation Reference

• src/jvlink_mcp_server/database/sample_data_provider.py:130-195 (handler)

  Core implementation of get_column_value_examples - the actual database query logic that retrieves unique column values grouped by count, with validation of table/column names and a limit parameter.

  def get_column_value_examples(
      db_connection,
      table_name: str,
      column_name: str,
      limit: int = 10
  ) -> Dict[str, Any]:
      """特定カラムの値の例を取得
  
      Args:
          db_connection: DatabaseConnectionインスタンス
          table_name: テーブル名
          column_name: カラム名
          limit: 取得する値の種類数
  
      Returns:
          dict: {
              'column_name': カラム名,
              'unique_values': ユニークな値のリスト,
              'value_counts': 値ごとの件数（上位10件）
          }
      """
      validate_identifier(table_name, "table name")
      validate_identifier(column_name, "column name")
  
      # テーブル名・カラム名のホワイトリスト検証
      valid_tables = db_connection.get_tables()
      if table_name not in valid_tables:
          return {"table_name": table_name, "column_name": column_name, "error": f"テーブル '{table_name}' は存在しません。"}
  
      try:
          schema_df = db_connection.get_table_schema(table_name)
          valid_columns = set(schema_df["column_name"].tolist())
          if column_name not in valid_columns:
              return {"table_name": table_name, "column_name": column_name, "error": f"カラム '{column_name}' は存在しません。"}
      except Exception as e:
          return {"table_name": table_name, "column_name": column_name, "error": str(e)}
  
      # limit上限
      limit = min(max(1, limit), 100)
  
      # ユニーク値取得
      sql = f"""
      SELECT {column_name}, COUNT(*) as cnt
      FROM {table_name}
      WHERE {column_name} IS NOT NULL AND {column_name} != ''
      GROUP BY {column_name}
      ORDER BY cnt DESC
      LIMIT {limit}
      """
  
      try:
          df = db_connection.execute_safe_query(sql)
  
          return {
              "table_name": table_name,
              "column_name": column_name,
              "unique_values": df[column_name].tolist(),
              "value_counts": df.to_dict(orient="records"),
              "description": _get_column_description(table_name, column_name),
          }
      except Exception as e:
          return {
              "table_name": table_name,
              "column_name": column_name,
              "error": str(e),
          }

• src/jvlink_mcp_server/server.py:678-685 (registration)

  MCP tool registration of 'get_column_examples' using @mcp.tool() decorator. Delegates to _get_column_value_examples (imported from sample_data_provider).

  @mcp.tool()
  def get_column_examples(table_name: str, column_name: str, limit: int = 10) -> dict:
      """特定カラムの値の例を取得（データ形式理解用）"""
      with DatabaseConnection() as db:
          return _get_column_value_examples(
              db, table_name=table_name,
              column_name=column_name, limit=limit
          )

• src/jvlink_mcp_server/server.py:42-46 (helper)

  Import of get_column_value_examples from sample_data_provider, aliased as _get_column_value_examples.

  from .database.sample_data_provider import (
      get_sample_data as _get_sample_data,
      get_column_value_examples as _get_column_value_examples,
      get_data_snapshot as _get_data_snapshot,
  )

• src/jvlink_mcp_server/database/sample_data_provider.py:315-318 (helper)

  Helper function _get_column_description used within get_column_value_examples to look up column descriptions.

  def _get_column_description(table_name: str, column_name: str) -> str:
      """カラムの説明を取得"""
      descriptions = _get_column_info(table_name)
      return descriptions.get(column_name, "説明なし")

• src/jvlink_mcp_server/database/sample_data_provider.py:341-347 (schema)

  Module __all__ exports, listing get_column_value_examples as a public interface.

  __all__ = [
      "get_sample_data",
      "get_column_value_examples",
      "get_data_snapshot",
      "IMPORTANT_COLUMNS",
      "clear_cache",
  ]